Skip to content

Commit

Permalink
Clarify two guides and two intro pages
Browse files Browse the repository at this point in the history 
See #11841

Make the Adding Nodes guide more usable for Cloud

- Add a ca_pin preset
- Clarify that tctl must be run on the local machine for Cloud users
- Structure the guide as a step-by-step tutorial. The guide already
  included sequences of sample commands, so all this took was to rename
  headings according to the "Step n/d." format and move the CA pinning
  section into the section on starting the Node.
- Add environment variables to use for storing a CA pin and invite
  token to sample commands, plus piped commands to extract these
  strings from the output of tctl commands.
- Use a ScopedBlock to hide the Node Tunneling section for Cloud users
- Indicate that the --auth-server flag in "teleport start" requires a
  port.

Add intros to the Admin and Operations menu pages

- Clarify the purpose of the Admin Guides and Operations sections
  by adding an intro paragraph to each page. Since these sections are
  similar in scope, I added links from one to the other with statements
  about how the two sections differ.

- Replace lists of links with Tiles.

GitHub SSO

- Move the step to create an OAuth app out of the Prerequisites and
  into its own step. This makes it easier to give the instructions
  to use a specific callback URL proper space.
- Be more explicit about the rp_ip value.
- Add explicit instructions for logging in to the cluster after
  creating the auth preference, including screenshots of expected
  results.
  • Loading branch information
@ptgott
ptgott committed Apr 15, 2022
1 parent cabfcdb commit 5650eb7
Show file tree
Hide file tree
Showing 8 changed files with 240 additions and 141 deletions.
3 changes: 2 additions & 1 deletion docs/config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -867,7 +867,8 @@
"first": "abcd123-insecure-do-not-use-this",
"second": "efgh456-insecure-do-not-use-this",
"third": "ijkl789-insecure-do-not-use-this"
}
},
"ca_pin": "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678"
},
"fedramp": {
"control_url": "https://csrc.nist.gov/Projects/risk-management/sp800-53-controls/release-search#!/control?version=5.1&number="
Expand Down
Binary file added docs/img/github-sso-auth-screen.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/login-success.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/pages/includes/tctl.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,6 @@ $ tctl status
# CA pin sha256:sha-hash-here
```

You can run subsequent `tctl` commands in this guide on your local machine.
You must run subsequent `tctl` commands in this guide on your local machine.

</Details>
74 changes: 48 additions & 26 deletions docs/pages/setup/admin.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,51 @@ description: Teleport Cluster Administration Guides.
layout: tocless-doc
---

<ul>
<li>
[Github SSO](./admin/github-sso.mdx). Setup single sign-on with Github.
</li>
<li>
[Adding nodes](./admin/adding-nodes.mdx). How to add new nodes to the cluster.
</li>
<li>
[Trusted Clusters](./admin/trustedclusters.mdx). Connect multiple Teleport clusters using Trusted Clusters.
</li>
<li>
[Labels](./admin/labels.mdx). Manage nodes metadata with resource labels.
</li>
<li>
[Local Users](./admin/users.mdx). Manage local user accounts.
</li>
<li>
[Troubleshooting](./admin/troubleshooting.mdx). Collect metrics and diagnostic information from Teleport.
</li>
<li>
[Signals and Graceful Restarts](./admin/graceful-restarts.mdx). Send signals to configure and restart Teleport without losing connections.
</li>
<li>
[Teleport Daemon](./admin/daemon.mdx). Setup and configure Teleport Linux Daemon as as Systemd unit.
</li>
</ul>
The guides in this section show you the fundamentals of setting up and running a
Teleport cluster. You will learn how to run the `teleport` daemon, manage users
and resources, and troubleshoot any issues that arise.

If you already understand how to set up a Teleport cluster, you should consult
the [Operations](./operations.mdx) section so you can start conducting periodic
cluster maintenance tasks.

## Run Teleport

<TileSet>
<Tile href="./admin/daemon.mdx" title="Teleport Daemon" icon="wrench">
Set up Teleport as a systemd unit.
</Tile>
<Tile href="./admin/graceful-restarts.mdx" title="Signals and Graceful Restarts" icon="wrench">
Send signals to configure and restart Teleport without losing connections.
</Tile>
</TileSet>

## Manage users and resources

<TileSet>
<Tile href="./admin/github-sso.mdx" title="GitHub SSO" icon="wrench">
Set up single sign-on with GitHub.
</Tile>
<Tile href="./admin/adding-nodes.mdx" title="Adding Nodes" icon="wrench">
How to add Nodes to your Teleport cluster.
</Tile>
<Tile href="./admin/trustedclusters.mdx" title="Trusted Clusters" icon="wrench">
Connect multiple Teleport clusters using Trusted Clusters.
</Tile>
<Tile href="./admin/labels.mdx" title="Labels" icon="wrench">
Manage resource metadata with labels.
</Tile>
<Tile href="./admin/users.mdx" title="Local Users" icon="wrench">
Manage local user accounts.
</Tile>
</TileSet>

## Troubleshoot issues

<TileSet>
<Tile href="./admin/troubleshooting.mdx" title="Troubleshooting" icon="wrench">
Collect metrics and diagnostic information from Teleport.
</Tile>
</TileSet>


195 changes: 109 additions & 86 deletions docs/pages/setup/admin/adding-nodes.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,39 +9,77 @@ This guide explains how to add Teleport Nodes to your cluster.

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

- A Linux server that you will use to host your Teleport Node

(!docs/pages/includes/tctl.mdx!)

## Adding Nodes to the cluster
## Step 1/3. Install Teleport on your Node

On the Linux server that you will use for your Teleport Node, run the appropriate installation commands for your platform:

(!docs/pages/includes/install-linux.mdx!)

## Step 2/3. Join your Node to the cluster

In this section, we will join your Node to the Teleport cluster by:

- Obtaining information stored on the Auth Service
- Starting Teleport on your Node with the information we obtained

### Obtain a CA pin

In a zero-trust environment, you must assume that an attacker can hijack the IP
address of the Auth Service.

To prevent this from happening, you need to supply every new Node with
information about the Auth Service. This technique is called **CA pinning**. It
works by asking the Auth Service to produce a CA pin, a hash value of the SPKI
header in a certificate. This way, an attacker cannot easily forge a matching
private key.

Retrieve the CA pin of the Auth Service <ScopedBlock scope="cloud"> by running the following
command on your local machine</ScopedBlock>:

```code
$ export CA_PIN=$(tctl status | awk '/CA pin/{print $3}')
# Cluster staging.example.com
# User CA never updated
# Host CA never updated
# CA pin (=presets.ca_pin=)
```

### Generate a token

Teleport only allows access to Nodes that have joined the cluster.

Once a Node joins, it receives its own host certificate signed by the cluster's
Once a Node joins, it receives a host certificate signed by the cluster's
Auth Service. To receive a host certificate upon joining a cluster, a new
Teleport host must present an **invite token**.

An invite token also defines which role a new host can assume within a cluster:
`auth`, `proxy`, `node`, `app`, `kube`, or `db`.

### Generate a token

Administrators can generate tokens as they are needed. A token can be used
multiple times until its time to live (TTL) expires.

Use the `tctl` tool to generate a new token. In the following example, a new
Use the `tctl` tool <ScopedBlock scope="cloud">on your local
machine</ScopedBlock> to generate a new token. In the following example, a new
token is created with a TTL of five minutes:

```code
# Generate a short-lived invitation token for a new node:
$ tctl nodes add --ttl=5m --roles=node
# The invite token: (=presets.tokens.first=)
# Generate a short-lived invite token for a new node:
$ export INVITE_TOKEN=$(tctl nodes add --ttl=5m --roles=node | grep "invite token:" | grep -Eo "[0-9a-z]{32}")
$ echo ${INVITE_TOKEN}
# (=presets.tokens.first=)
# You can also list all generated non-expired tokens:
$ tctl tokens ls
# Token Type Expiry Time
# ------------------------ ----------- ---------------
# (=presets.tokens.first=) Node 25 Sep 18 00:21 UTC
# ... or revoke an invitation token before it's used:
# ... or revoke an invite token before it's used:
$ tctl tokens rm (=presets.tokens.first=)
```

Expand Down Expand Up @@ -74,36 +112,53 @@ auth_service:
```
</Details>
### Using Node invitation tokens
### Start your Node with the invite token and CA pin
The CA pin at the needs to be passed to new Nodes when they're
starting for the first time, i.e. when they join a cluster.
If a CA pin is not provided, the Teleport Node will join a cluster but it will
print a `WARN` message (warning).

<Notice type="warning">

The CA pin becomes invalid if a Teleport administrator performs the CA rotation
by executing [`tctl auth rotate`](../reference/cli.mdx#tctl-auth-rotate).

</Notice>


<Tabs>
<TabItem scope={["oss", "enterprise"]} scopeOnly={true} label="Self Hosted">
Execute one of the following commands on a new Node to add it to a cluster:
```code
# Adding an SSH Node to the cluster:
$ sudo teleport start --roles=node --token=(=presets.tokens.first=) --auth-server=10.0.10.5

# Adding a new regular SSH Node using Teleport Node Tunneling:
$ sudo teleport start --roles=node --token=(=presets.tokens.first=) --auth-server=teleport-proxy.example.com:3080
Execute one of the following commands on a new Node to add it to a cluster.
Supply the invite token and CA pin you retrieved earlier:

# Adding a new Proxy Service to the cluster:
$ sudo teleport start --roles=proxy --token=(=presets.tokens.first=) --auth-server=10.0.10.5
```code
$ sudo teleport start \
--roles=node \
--token=(=presets.tokens.first=) \
--ca-pin=(=presets.ca_pin=) \
--auth-server=10.12.0.6:3025
```
</TabItem>
<TabItem scope={["cloud"]} scopeOnly={true} label="Teleport Cloud">

Execute the following command on a new Node to add it to a cluster. Replace
`mytenant.teleport.sh` with the domain name of your Teleport Cloud tenant.
Supply the invite token and CA pin you retrieved earlier:

```code
# Adding an SSH Node to the cluster:
$ sudo teleport start --roles=node --token=(=presets.tokens.first=) --auth-server=mytenant.teleport.sh
$ sudo teleport start \
--roles=node \
--token=(=presets.tokens.first=) \
--ca-pin=(=presets.ca_pin=) \
--auth-server=https://mytenant.teleport.sh:443
```

</TabItem>
</Tabs>


As new Nodes come online, they start sending ping requests every few seconds to
the Auth Service. This allows users to explore cluster membership and size:

Expand All @@ -120,7 +175,10 @@ dijkstra c9s93fd9-3333-91d3-9999-c9s93fd98f43 10.1.0.6:3022 distro
as a workaround until we have a way to control the visibility of subsections
using the scope switcher */}

<Details scope={["oss", "enterprise"]} scopeOnly={true} title="Node Tunneling" opened>
<ScopedBlock scope={["oss", "enterprise"]}>

### Teleport Node Tunneling

Teleport Node Tunneling lets you add a remote Node to an existing Teleport Cluster through a tunnel.
This can be useful for IoT applications or for managing a couple of servers in a different network.

Expand Down Expand Up @@ -178,14 +236,36 @@ DEBU [PROC:1] Setup Proxy: Reverse tunnel proxy and web proxy listen on the s
uses a round-robin or a similar balancing algorithm. Do not use sticky load balancing algorithms (a.k.a. "session affinity") with Teleport Proxy Service instances.
</Admonition>

</Details>
</ScopedBlock>

## Revoking invitations
## Step 3/3. Revoke an invitation

Tokens used for joining Nodes to a cluster can be revoked before they are used.
To see a list of outstanding tokens, run this command:

Run the following command to create a token for a new Proxy Service.

```code
$ tctl nodes add --ttl=5m --roles=proxy
# The invite token: (=presets.tokens.first=).
# This token will expire in 5 minutes.
#
# Run this on the new node to join the cluster:
#
# > teleport start \
# --roles=proxy \
# --token=(=presets.tokens.first=) \
# --ca-pin=(=presets.ca_pin=) \
# --auth-server=123.123.123.123:3025
#
# Please note:
#
# - This invitation token will expire in 5 minutes
# - 123.123.123.123 must be reachable from the new node
```

Next, run the following command to see a list of outstanding tokens:

```
$ tctl tokens ls
# Token Role Expiry Time (UTC)
Expand All @@ -208,67 +288,10 @@ static token configured via a config file.
The token with the `Node` role was generated to invite a new Node to this
cluster. And the third token was generated to invite a new user to sign up.

The latter two tokens can be deleted (revoked) via the `tctl tokens
del` command:
Tokens created via `tctl` can be deleted (revoked) via the `tctl tokens del`
command. Run the following command to delete a token:

```code
$ tctl tokens del (=presets.tokens.first=)
# Token (=presets.tokens.first=) has been deleted
```

## Untrusted Auth Servers

Teleport Nodes use the HTTPS protocol to offer an invite token to the Auth Service.
In a zero-trust environment, you must assume that an attacker can hijack the IP
address of the Auth Service.

To prevent this from happening, you need to supply every new Node with an
additional bit of information about the Auth Service. This technique is called
**CA pinning**. It works by asking the Auth Service to produce a CA pin, a hash
value of the SPKI header in a certificate. This way, an attacker cannot easily
forge a matching private key.

Retrieve the CA pin of the Auth Service:

```code
$ tctl status
# Cluster staging.example.com
# User CA never updated
# Host CA never updated
# CA pin sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1
```

The CA pin at the bottom needs to be passed to new Nodes when they're
starting for the first time, i.e. when they join a cluster. Here is an
example of running `teleport start` on a Node with a CA pin:

```code
$ sudo teleport start \
--roles=node \
--token=(=presets.tokens.first=) \
--ca-pin=sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1 \
--auth-server=10.12.0.6:3025
```

You can also supply a CA pin by modifying `/etc/teleport.yaml` on a Node:

```yaml
teleport:
auth_token: "(=presets.tokens.first=)"
ca_pin: "sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1"
auth_servers:
- "10.12.0.6:3025"
```
<Admonition
type="warning"
title="Warnings"
>
- If a CA pin is not provided, the Teleport Node will join a cluster but it will
print a `WARN` message (warning).
- The CA pin becomes invalid if a Teleport administrator
performs the CA rotation by executing
[`tctl auth rotate`](../reference/cli.mdx#tctl-auth-rotate) .
</Admonition>

```
Loading

0 comments on commit 5650eb7

Please sign in to comment.