Skip to content

Commit

Permalink
Standardize ACME instruction details (#11009)
Browse files Browse the repository at this point in the history
Backports #9556

* 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

* 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
  • Loading branch information
ptgott authored Mar 18, 2022
1 parent 2548a45 commit 927d638
Show file tree
Hide file tree
Showing 6 changed files with 111 additions and 82 deletions.
6 changes: 2 additions & 4 deletions docs/pages/application-access/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ $ docker run -d -p 3000:3000 grafana/grafana

## Step 2/3. Install and configure Teleport

(!docs/pages/includes/permission-warning.mdx!)

On your Application Service host, download the latest version of Teleport for
your platform from our
[downloads page](https://goteleport.com/teleport/download).
Expand All @@ -57,9 +59,6 @@ $ tctl tokens add \

### Start Teleport

On the host where you will run the Teleport Application Service, download the latest version of Teleport for your platform from our
[downloads page](https://goteleport.com/teleport/download).

Now start Teleport and point it to the application endpoint:

```code
Expand All @@ -77,7 +76,6 @@ Make sure to update `--app-name` and `--app-uri` accordingly if you're using you
The `--token` flag points to the file on the Application Service host where we stored the token that we generated earlier.

### 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
Expand Down
34 changes: 9 additions & 25 deletions docs/pages/application-access/guides/connecting-apps.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
29 changes: 10 additions & 19 deletions docs/pages/database-access/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -73,33 +73,22 @@ 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).

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 node where you're launching Teleport.
### Configure TLS

Let's generate a Teleport config with ACME enabled:
Teleport requires a valid TLS certificate to operate and can fetch one automatically
using Let's Encrypt.

```code
$ teleport configure --cluster-name=teleport.example.com --acme [email protected] > /tmp/teleport.yaml
```
(!docs/pages/includes/acme.mdx!)

<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>
### Start Teleport

Now start Teleport and point it to your Aurora database instance. Make sure to
update the database endpoint and region appropriately.
Expand All @@ -118,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).
</Admonition>

### Create a user and role

Create the role that will allow a user to connect to any database using any
database account:

Expand Down
58 changes: 40 additions & 18 deletions docs/pages/getting-started/linux-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,24 +25,37 @@ Take a look at the [Installation Guide](../installation.mdx) for more options.

### Configure Teleport

Generate a configuration file for Teleport using `teleport configure`.
Teleport requires TLS credentials to provide a secure public endpoint for the
Teleport UI and for end-users to connect to.

Acme turns on automatic TLS certificates from [Let's Encrypt](https://letsencrypt.org).
You can either configure Teleport to obtain a TLS certificate via Let's Encrypt
or use an existing certificate and private key.

Set up an email to receive updates from Let's Encrypt, and use a valid DNS name for a cluster name.
<Tabs>
<TabItem label="Public internet deployment with Let's Encrypt">

```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!
```
(!docs/pages/includes/acme.mdx!)

</TabItem>

<TabItem label="Private net deployment">
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.

{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */}
The leaf certificate must have a subject that corresponds to the domain of your Teleport host, e.g., `*.teleport.example.com`.

### Configure domain name and obtain TLS certificates using Let's Encrypt
Configure Teleport, changing the values of the `--cluster-name` and `--public-addr` flags to match the domain name of your Teleport host.

Teleport requires a secure public endpoint for the Teleport UI and for end-users to connect to.
To get started, set up two `A` records for `tele.example.com` and `*.tele.example.com`
pointing to the IP/FQDN of the machine with Teleport installed.
```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
```
</TabItem>

</Tabs>

<Admonition
type="tip"
Expand All @@ -55,15 +68,24 @@ pointing to the IP/FQDN of the machine with Teleport installed.
```
</Admonition>

Start Teleport:

```code
$ sudo teleport start
```
### Start Teleport

You can access Teleport's Web UI on port `443`.
<Tabs>
<TabItem label="Package manager RPM/DEB">
```code
$ sudo systemctl start teleport
```
</TabItem>

<TabItem label="Source or custom install">
```code
$ sudo teleport start
```
</TabItem>
</Tabs>

Replace `tele.example.com` with your domain: `https://tele.example.com/`.
You can access Teleport's Web UI via HTTPS at the domain you created earlier.

## Step 2/4. Create a Teleport user and set up two-factor authentication

Expand Down
23 changes: 23 additions & 0 deletions docs/pages/includes/acme.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
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 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 `[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 > /etc/teleport.yaml
```

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.
43 changes: 27 additions & 16 deletions docs/pages/includes/database-access/start-auth-proxy.mdx
Original file line number Diff line number Diff line change
@@ -1,29 +1,41 @@
<Tabs>
<TabItem scope={["oss","enterprise"]} label="Self Hosted">
<TabItem scope={["oss","enterprise"]} label="Self-Hosted">
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).

Teleport requires a valid TLS certificate to operate and can fetch one
automatically using Let's Encrypt's ACME protocol. Before Let's Encrypt can
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.
You can configure the Teleport Proxy service to complete the Let's Encrypt
verification process when it starts up.

<Admonition type="note" title="Web Proxy Port">
To support the ACME protocol, Teleport Proxy must listen on port 443, rather
than the default port 3080.
</Admonition>

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:
Run 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 --cluster-name=teleport.example.com --acme [email protected] -o file
teleport configure --acme [email protected] --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:

```yaml
proxy_service:
enabled: "yes"
web_listen_addr: :443
public_addr: tele.example.com:443
acme:
enabled: "yes"
email: [email protected]
```
Start the Teleport Auth and Proxy services:
Port 443 on your Teleport Proxy Service host must allow traffic from all sources.
Next, start the Teleport Auth and Proxy Services:
```code
$ sudo teleport start
Expand All @@ -45,4 +57,3 @@ $ tctl status
```
</TabItem>
</Tabs>

0 comments on commit 927d638

Please sign in to comment.