From c9cc176ca7cb453b3bb41fe81bccc05cc3d5e61d Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 23 Dec 2021 11:47:35 -0500 Subject: [PATCH 1/2] Standardize ACME instruction details Our Getting Started guides often include instructions for configuring Let's Encrypt and ACME before starting Teleport, but not all of these instructions have the same level of detail, and some are missing some context around how Teleport uses ACME and why you need to open port 443 on your Proxy Service host. This change adds an include that spells out these instructions and invokes the include in the appropriate guides. The intention was to include as much relevant information within the guides themselves to prevent the reader from having to navigate to other pages. Closes #6448 --- .../application-access/getting-started.mdx | 20 ++--------- .../guides/connecting-apps.mdx | 34 +++++-------------- .../pages/database-access/getting-started.mdx | 20 ++--------- docs/pages/getting-started/linux-server.mdx | 13 +------ docs/pages/includes/acme.mdx | 21 ++++++++++++ .../database-access/start-auth-proxy.mdx | 12 +++---- docs/pages/server-access/getting-started.mdx | 10 ++---- 7 files changed, 44 insertions(+), 86 deletions(-) create mode 100644 docs/pages/includes/acme.mdx diff --git a/docs/pages/application-access/getting-started.mdx b/docs/pages/application-access/getting-started.mdx index 9b107f121a734..785ee588fa51d 100644 --- a/docs/pages/application-access/getting-started.mdx +++ b/docs/pages/application-access/getting-started.mdx @@ -31,31 +31,17 @@ $ docker run -d -p 3000:3000 grafana/grafana ``` ## Step 2/3. Install and configure Teleport +(!docs/pages/includes/permission-warning.mdx!) Download the latest version of Teleport for your platform from our [downloads page](https://goteleport.com/teleport/download). -Teleport requires a valid TLS certificate to operate and can fetch one automatically -using Let's Encrypt [ACME](https://letsencrypt.org/how-it-works/) protocol. - We will assume that you have configured DNS records for `teleport.example.com` and `*.teleport.example.com` to point to the Teleport node. -(!docs/pages/includes/permission-warning.mdx!) - -Let's generate a Teleport config with ACME enabled: - -```code -$ sudo teleport configure --cluster-name=teleport.example.com --acme --acme-email=alice@example.com -o file -``` +Teleport uses TLS to communicate with clients, and can fetch certificates automatically via Let's Encrypt. - - Teleport uses [TLS-ALPN-01](https://letsencrypt.org/docs/challenge-types/#tls-alpn-01) - ACME challenge to validate certificate requests which only works on port `443`. Make sure your Teleport proxy is accessible on port `443` when using ACME for certificate management. - +(!docs/pages/includes/acme.mdx!) Now start Teleport and point it to the application endpoint: diff --git a/docs/pages/application-access/guides/connecting-apps.mdx b/docs/pages/application-access/guides/connecting-apps.mdx index 4468d6544d894..e13f68ec7af53 100644 --- a/docs/pages/application-access/guides/connecting-apps.mdx +++ b/docs/pages/application-access/guides/connecting-apps.mdx @@ -59,31 +59,13 @@ 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`. -Teleport can obtain a certificate automatically from Let's Encrypt using -[ACME](https://letsencrypt.org/how-it-works/) protocol. - -Enable ACME in your proxy config: - -```yaml -proxy_service: - enabled: "yes" - web_listen_addr: "0.0.0.0:443" - public_addr: "teleport.example.com:443" - acme: - enabled: "yes" - email: alice@example.com -``` - - - Teleport uses [TLS-ALPN-01](https://letsencrypt.org/docs/challenge-types/#tls-alpn-01) - ACME challenge to validate certificate requests which only works on port `443`. Make sure your Teleport proxy is accessible on port `443` when using ACME for certificate management. - - -Alternatively, if you have obtained certificate/key pairs for your domain -(e.g. using [certbot](https://certbot.eff.org/)), they can be provided directly +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 @@ -97,6 +79,8 @@ proxy_service: - key_file: "/etc/letsencrypt/live/*.teleport.example.com/privkey.pem" cert_file: "/etc/letsencrypt/live/*.teleport.example.com/fullchain.pem" ``` + + ### Create a user diff --git a/docs/pages/database-access/getting-started.mdx b/docs/pages/database-access/getting-started.mdx index 51e4f6ff3cc42..2fd4868f87660 100644 --- a/docs/pages/database-access/getting-started.mdx +++ b/docs/pages/database-access/getting-started.mdx @@ -81,25 +81,9 @@ Download the appropriate version of Teleport for your platform from our [downloads page](https://goteleport.com/teleport/download). Teleport requires a valid TLS certificate to operate and can fetch one automatically -using Let's Encrypt [ACME](https://letsencrypt.org/how-it-works/) protocol. +using Let's Encrypt. -We will assume that you have configured DNS records for `teleport.example.com` and -`*.teleport.example.com` to point to the node where you're launching Teleport. - -Let's generate a Teleport config with ACME enabled: - -```code -$ teleport configure --cluster-name=teleport.example.com --acme --acme-email=alice@example.com > /tmp/teleport.yaml -``` - - - Teleport's ACME protocol integration currently requires web proxy to run on - port 443 so open /tmp/teleport.yaml and update `proxy_service.web_listen_addr` - and `proxy_service.public_addr` to use port 443 instead of the default 3080. - +(!docs/pages/includes/acme.mdx!) Now start Teleport and point it to your Aurora database instance. Make sure to update the database endpoint and region appropriately. diff --git a/docs/pages/getting-started/linux-server.mdx b/docs/pages/getting-started/linux-server.mdx index f6a450cbd9872..d22847729205c 100644 --- a/docs/pages/getting-started/linux-server.mdx +++ b/docs/pages/getting-started/linux-server.mdx @@ -49,18 +49,7 @@ Next, generate a configuration file for Teleport using the `teleport configure` - Teleport uses the ACME protocol to request automatic TLS certificates from Let's Encrypt, which accesses an HTTP endpoint on your Teleport host in order to complete authentication challenges. - - Use the following command to configure Teleport: - - ```code - $ sudo teleport configure --acme --acme-email=your-email@example.com --cluster-name=tele.example.com -o file - # Wrote config to file "/etc/teleport.yaml". Now you can start the server. Happy Teleporting! - ``` - - The `--acme-email` flag indicates an email address that Let's Encrypt can use for notifications, and does *not* require the same domain name as your Teleport host. - - For the `--cluster-name` flag, enter the domain name you used when creating a DNS A record earlier. + (!docs/pages/includes/acme.mdx!) diff --git a/docs/pages/includes/acme.mdx b/docs/pages/includes/acme.mdx new file mode 100644 index 0000000000000..8464812a887d4 --- /dev/null +++ b/docs/pages/includes/acme.mdx @@ -0,0 +1,21 @@ +Let's Encrypt verifies that you control the domain name of your Teleport deployment by communicating with the HTTPS server listening on port 443 of your Teleport Proxy Service. + +You can configure Teleport to complete the Let's Encrypt verification process—called the ACME protocol—by running 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 +teleport configure --acme --acme-email=user@example.com --cluster-name=tele.example.com +``` + +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: :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. diff --git a/docs/pages/includes/database-access/start-auth-proxy.mdx b/docs/pages/includes/database-access/start-auth-proxy.mdx index c9492a4a29472..37b95327ac65c 100644 --- a/docs/pages/includes/database-access/start-auth-proxy.mdx +++ b/docs/pages/includes/database-access/start-auth-proxy.mdx @@ -6,7 +6,7 @@ issue a TLS certificate for the Teleport Proxy host's domain, the ACME protocol must verify that an HTTPS server is reachable on port 443 of the host. We will assume that you have configured DNS records for `teleport.example.com` -and `*.teleport.example.com` to point to your Teleport node. +and `*.teleport.example.com` to point to your Teleport Node. To support the ACME protocol, Teleport Proxy must listen on port 443, rather @@ -17,13 +17,13 @@ Download the latest version of Teleport for your platform from our [downloads page](https://goteleport.com/teleport/download) and follow the installation [instructions](../../installation.mdx). -Generate a Teleport configuration file with ACME enabled: +Teleport requires a valid TLS certificate to operate and can fetch one automatically +using Let's Encrypt. +We will assume that you have configured DNS records for `teleport.example.com` and `*.teleport.example.com` to point to the Teleport Node. -```code -$ teleport configure --cluster-name=teleport.example.com --acme --acme-email=alice@example.com -o file -``` +(!docs/pages/includes/acme.mdx!) -Start the Teleport Auth and Proxy services: +Next, start the Teleport Auth and Proxy Services: ```code $ sudo teleport start diff --git a/docs/pages/server-access/getting-started.mdx b/docs/pages/server-access/getting-started.mdx index db77a4a1b656e..f1c88a5a89686 100644 --- a/docs/pages/server-access/getting-started.mdx +++ b/docs/pages/server-access/getting-started.mdx @@ -70,15 +70,9 @@ This guide introduces some of these common scenarios and how to interact with Te 3. Configure Teleport on the *Bastion Host*. - Teleport will now automatically acquire an X.509 certificate using the ACME protocol. + Teleport uses TLS to communicate with clients, and can fetch certificates automatically via Let's Encrypt. - ```code - # Configure Teleport with TLS certs - $ sudo teleport configure \ - --acme --acme-email=your_email@example.com \ - --cluster-name=tele.example.com \ - -o file - ``` + (!docs/pages/includes/acme.mdx!) Run the command above on `tele.example.com`. From aa0767070366cf839bbc6336bf186ce321834346 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 10 Feb 2022 11:14:04 -0500 Subject: [PATCH 2/2] Respond to PR feedback - Substitute "proxy" for "node" where it was incorrectly used - Some small stylistic fixes - Clarify that "teleport configure" does not write the config itself --- docs/pages/application-access/getting-started.mdx | 5 ++++- docs/pages/database-access/getting-started.mdx | 13 ++++++++++--- docs/pages/includes/acme.mdx | 8 +++++--- 3 files changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/pages/application-access/getting-started.mdx b/docs/pages/application-access/getting-started.mdx index 785ee588fa51d..0c3f6f5440f9e 100644 --- a/docs/pages/application-access/getting-started.mdx +++ b/docs/pages/application-access/getting-started.mdx @@ -37,12 +37,14 @@ Download the latest version of Teleport for your platform from our [downloads page](https://goteleport.com/teleport/download). We will assume that you have configured DNS records for `teleport.example.com` -and `*.teleport.example.com` to point to the Teleport node. +and `*.teleport.example.com` to point to the Teleport Proxy Service. +### Configure TLS Teleport uses TLS to communicate with clients, and can fetch certificates automatically via Let's Encrypt. (!docs/pages/includes/acme.mdx!) +### Start Teleport Now start Teleport and point it to the application endpoint: ```code @@ -55,6 +57,7 @@ $ sudo teleport start \ Make sure to update `--app-name` and `--app-uri` accordingly if you're using your own web application. +### Create a user Next, let's create a user to access the application we've just connected. Teleport has a built-in role called `access` that allows users to access cluster resources. Create a local user assigned this role: ```code diff --git a/docs/pages/database-access/getting-started.mdx b/docs/pages/database-access/getting-started.mdx index 2fd4868f87660..7bf0d0d550b71 100644 --- a/docs/pages/database-access/getting-started.mdx +++ b/docs/pages/database-access/getting-started.mdx @@ -14,7 +14,7 @@ Here's an overview of what we will do: 2. Download and install Teleport (=teleport.version=) and connect it to the Aurora database. 3. Connect to the Aurora database via Teleport. -## Step 1/3. Setup Aurora +## Step 1/3. Set up Aurora In order to allow Teleport connections to an Aurora instance, it needs to support IAM authentication. @@ -73,18 +73,23 @@ GRANT rds_iam TO alice; For more information about connecting to the PostgreSQL instance directly, see Amazon [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html). -## Step 2/3. Setup Teleport +## Step 2/3. Set up Teleport Teleport Database Access is available starting from `6.0.0` release. Download the appropriate version of Teleport for your platform from our [downloads page](https://goteleport.com/teleport/download). + +### Configure TLS + Teleport requires a valid TLS certificate to operate and can fetch one automatically using Let's Encrypt. (!docs/pages/includes/acme.mdx!) +### Start Teleport + Now start Teleport and point it to your Aurora database instance. Make sure to update the database endpoint and region appropriately. @@ -102,9 +107,11 @@ $ sudo teleport start --config=/tmp/teleport.yaml \ title="AWS Credentials" > The node that connects to the database should have AWS credentials configured - with the policy from [step 1](#step-13-setup-aurora). + with the policy from [step 1](#step-13-set-up-aurora). +### Create a user and role + Create the role that will allow a user to connect to any database using any database account: diff --git a/docs/pages/includes/acme.mdx b/docs/pages/includes/acme.mdx index 8464812a887d4..fb33518d61cdd 100644 --- a/docs/pages/includes/acme.mdx +++ b/docs/pages/includes/acme.mdx @@ -1,9 +1,11 @@ -Let's Encrypt verifies that you control the domain name of your Teleport deployment by communicating with the HTTPS server listening on port 443 of your Teleport Proxy Service. +Let's Encrypt verifies that you control the domain name of your Teleport deployment by communicating with the HTTPS server listening on port 443 of your Teleport Proxy Service. -You can configure Teleport to complete the Let's Encrypt verification process—called the ACME protocol—by running 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): +You can configure the Teleport Proxy service to complete the Let's Encrypt verification process when it starts up. + +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 -teleport configure --acme --acme-email=user@example.com --cluster-name=tele.example.com +teleport configure --acme --acme-email=user@example.com --cluster-name=tele.example.com > /etc/teleport.yaml ``` The `--acme`, `--acme-email`, and `--cluster-name` flags will add the following settings to your Teleport configuration file: