-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
Showing
7 changed files
with
44 additions
and
86 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 [email protected] -o file | ||
``` | ||
Teleport uses TLS to communicate with clients, and can fetch certificates automatically via Let's Encrypt. | ||
|
||
<Admonition | ||
type="note" | ||
title="Web Proxy Port" | ||
> | ||
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. | ||
</Admonition> | ||
(!docs/pages/includes/acme.mdx!) | ||
|
||
Now start Teleport and point it to the application endpoint: | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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: [email protected] | ||
``` | ||
<Admonition | ||
type="note" | ||
title="Web Proxy Port" | ||
> | ||
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. | ||
</Admonition> | ||
|
||
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/)). | ||
<Tabs> | ||
<TabItem label="Let's Encrypt"> | ||
(!docs/pages/includes/acme.mdx!) | ||
</TabItem> | ||
<TabItem label="Existing Credentials"> | ||
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" | ||
``` | ||
</TabItem> | ||
</Tabs> | ||
### Create a user | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 [email protected] > /tmp/teleport.yaml | ||
``` | ||
|
||
<Admonition | ||
type="warning" | ||
title="Web Proxy Port" | ||
> | ||
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. | ||
</Admonition> | ||
(!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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -49,18 +49,7 @@ Next, generate a configuration file for Teleport using the `teleport configure` | |
|
||
<Tabs> | ||
<TabItem label="Public internet deployment with Let's Encrypt"> | ||
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 [email protected] --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!) | ||
|
||
</TabItem> | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 `[email protected]` is an email address used for notifications (you can use any domain): | ||
|
||
```code | ||
teleport configure --acme [email protected] --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: [email protected] | ||
``` | ||
Port 443 on your Teleport Proxy Service host must allow traffic from all sources. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
|
||
<Admonition type="note" title="Web Proxy Port"> | ||
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 [email protected] -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 | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 [email protected] \ | ||
--cluster-name=tele.example.com \ | ||
-o file | ||
``` | ||
(!docs/pages/includes/acme.mdx!) | ||
|
||
Run the command above on `tele.example.com`. | ||
|
||
|