diff --git a/docs/pages/access-controls/getting-started.mdx b/docs/pages/access-controls/getting-started.mdx index e43ff29ad4738..8271697eb38a8 100644 --- a/docs/pages/access-controls/getting-started.mdx +++ b/docs/pages/access-controls/getting-started.mdx @@ -16,6 +16,8 @@ with creating your own role. - Installed [Teleport](../getting-started.mdx) or [Teleport Cloud](../cloud/introduction.mdx) >= (=teleport.version=) - [Tctl admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=) +(!docs/pages/includes/permission-warning.mdx!) + Verify that your Teleport client is connected: ```bash diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index 69bc94079d9bf..e55187c9b2b56 100644 --- a/docs/pages/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/access-controls/guides/per-session-mfa.mdx @@ -1,6 +1,6 @@ --- title: Per-session MFA -description: Require U2F checks for user SSH and Kubernetes sessions +description: Require U2F checks for user SSH and Kubernetes sessions. --- # Per-session MFA diff --git a/docs/pages/access-controls/guides/role-templates.mdx b/docs/pages/access-controls/guides/role-templates.mdx index 51fc3bcd692ee..96002c219695d 100644 --- a/docs/pages/access-controls/guides/role-templates.mdx +++ b/docs/pages/access-controls/guides/role-templates.mdx @@ -1,6 +1,6 @@ --- title: Teleport Role Templates -description: Mapping SSO and Local Users Traits to Roles with Template +description: Mapping SSO and Local Users Traits to Roles with Template. --- # Role Templates diff --git a/docs/pages/access-controls/guides/u2f.mdx b/docs/pages/access-controls/guides/u2f.mdx index bc082d041b6ce..649b5ddc40e82 100644 --- a/docs/pages/access-controls/guides/u2f.mdx +++ b/docs/pages/access-controls/guides/u2f.mdx @@ -1,9 +1,9 @@ --- title: Second Factor - U2F -description: Configuring U2F support in Teleport clusters +description: Configuring U2F support in Teleport clusters. --- -# U2F +# U2F ( Hardware Tokens) Teleport supports [FIDO U2F](https://www.yubico.com/about/background/fido/) hardware keys as a second authentication factor. U2F can be used for logging diff --git a/docs/pages/access-controls/introduction.mdx b/docs/pages/access-controls/introduction.mdx index 1695fde280116..14d4762489f46 100644 --- a/docs/pages/access-controls/introduction.mdx +++ b/docs/pages/access-controls/introduction.mdx @@ -17,7 +17,7 @@ Role-Based Access Control (RBAC) is almost always used in conjunction with Singl It also works with users stored in Teleport's internal database. -## Getting Started +## Getting started Configure Access Controls in a 5 minute [Getting Started](./getting-started.mdx) guide. diff --git a/docs/pages/architecture/authentication.mdx b/docs/pages/architecture/authentication.mdx index dbbbea9a97e08..068c13ab8489b 100644 --- a/docs/pages/architecture/authentication.mdx +++ b/docs/pages/architecture/authentication.mdx @@ -1,5 +1,5 @@ --- -title: Teleport Authentication Service, SSH and Kubernetes certificates +title: Teleport Authentication Service, SSH, and Kubernetes certificates description: This chapter explains the concept of a Teleport Auth Service and Certificate Authority (CA) to issue SSH and Kubernetes certificates. h1: Teleport Authentication Service --- @@ -22,9 +22,7 @@ certificate issued by the Teleport Auth Certificate Authority. **Authorization** is proving access to something: "Bob has a purple hat, but also a debit card and the correct PIN code. Bob can access a bank account with -the number 814000001344. Can Bob get $20 out of the ATM?" The ATM's -Authentication system would validate Bob's PIN Code, while the Authorization -system would use a stored mapping from Bob to account #814000001344 to decide +the number 814000001344. Can Bob get $20 out of the ATM?" The ATM's Authentication system would validate Bob's PIN Code, while the Authorization system would use a stored mapping from Bob to account #814000001344 to decide whether Bob could withdraw cash. Authorization defines and determines permissions that users have within a system, such as access to cash within a banking system, or data in a filesystem. Before users are granted access to @@ -33,31 +31,28 @@ database. ![Authentication and Authorization](../../img/authn_authz.svg) -## SSH Certificates +## SSH certificates One can think of an SSH certificate as a "permit" issued and time-stamped by a -trusted authority. In this case the authority is the Auth Server's Certificate +trusted authority. In this case, the authority is the Auth Server's Certificate Authority. A certificate contains four important pieces of data: 1. List of principals (identities) this certificate belongs to. 2. Signature of the certificate authority who issued it. 3. The expiration date, also known as "time-to-live" or simply TTL. -4. Additional data, such as the node role, stored as a certificate extension. +4. Additional data, such as the node role, is stored as a certificate extension. ## Authentication in Teleport Teleport uses SSH certificates to authenticate nodes and users within a cluster. -There are two CAs operating inside the Auth Server because nodes and users each -need their own certificates. {/* TODO: Why? */} +Two CAs are used inside the Auth Server because nodes and users each need their own certificates. {/* TODO: Why? */} - The **Node CA** issues certificates which identify a node (i.e. host, server, - computer). These certificates are used to add new nodes to a cluster and - identify connections coming from the node. -- The **User CA** issues certificates which identify a User. These certificates - are used to authenticate users when they try to connect to a cluster node. + computer). These certificates are used to add new nodes to a cluster and identify connections coming from the node. +- The **User CA** issues certificates which identify a User. These certificates are used to authenticate users when they try to connect to a cluster node. -### Issuing Node Certificates +### Issuing Node certificates Node Certificates identify a node within a cluster and establish the permissions of the node to access other Teleport services. The presence of a signed @@ -65,10 +60,7 @@ certificate on a node makes it a cluster member. ![Node Joins Cluster](../../img/node_join.svg) -1. To join a cluster for the first time, a node must present a "join token" to - the auth server. The token can be static (configured via config file) or a - dynamic, single-use token generated by [`tctl nodes - add`](../cli-docs.mdx#tctl-nodes-add). +1. To join a cluster for the first time, a node must present a "join token" to the auth server. The token can be static (configured via config file) or a dynamic, single-use token generated by [`tctl nodes add`](../cli-docs.mdx#tctl-nodes-add). -2. When a new node joins the cluster, the auth server generates a new - public/private keypair for the node and signs its certificate. This node - certificate contains the node's role(s) (`proxy`, `auth` or `node`) as a - certificate extension (opaque signed string). +2. When a new node joins the cluster, the auth server generates a new public/private keypair for the node and signs its certificate. This node certificate contains the node's role(s) (`proxy`, `auth` or `node`) as a certificate extension (opaque signed string). -### Using Node Certificates +### Using Node certificates ![Node Authorization](../../img/node_cluster_auth.svg) @@ -96,7 +85,7 @@ connection using a certificate with only the `node` role won't be able to add and delete users. This client connection would only be authorized to get auth servers registered in the cluster. -### Issuing User Certificates +### Issuing user certificates ![Client obtains new certificate](../../img/cert_invalid.svg) @@ -104,21 +93,15 @@ The Auth Server uses its User CA to issue user certificates. User certificates are stored on a user's machine in the `~/.tsh/keys/example.com` directory or also by the system's SSH agent if it is running. -1. To get permission to join a cluster for the first time a user must provide - their username, password, and 2nd-factor token. Users can log in with [`tsh - login`](../cli-docs.mdx#tsh-login) or via the Web UI. The Auth Server checks - the username and password against its identity storage and checks the 2nd factor token. -2. If the correct credentials were offered, the Auth Server will generate a - signed certificate and return it to the client. For users, certificates are - stored in `~/.tsh` by default. If the client uses the Web UI the signed certificate - is associated with a secure websocket session. +1. To get permission to join a cluster for the first time a user must provide their username, password, and 2nd-factor token. Users can log in with [`tsh login`](../cli-docs.mdx#tsh-login) or via the Web UI. The Auth server checks the username and password against its identity storage and checks the 2nd-factor token. +2. If the correct credentials were offered, the Auth Server will generate a signed certificate and return it to the client. For users, certificates are stored in `~/.tsh` by default. If the client uses the Web UI the signed certificate is associated with a secure WebSocket session. In addition to a user's identity, user certificates also contain user roles and SSH options, like "permit-agent-forwarding" {/* TODO: link to config/set options here */}. This additional data is stored as a certificate extension and is protected by the CA signature. -### Using User Certificates +### Using user certificates ![Client offers valid certificate](../../img/user_auth.svg) @@ -129,11 +112,9 @@ certificate is still valid, the Auth Server validates the certificate's signature. The client is then granted access to the cluster. From here, the [Proxy Server](proxy.mdx) establishes a connection between client and node. -## Certificate Rotation +## Certificate rotation -By default, all user certificates have an expiration date, also known as time to -live (TTL). This TTL can be configured by a Teleport administrator. However, the node -certificates issued by an Auth Server are valid indefinitely by default. +By default, all user certificates have an expiration date, also known as the *time to live *(TTL). This TTL can be configured by a Teleport administrator. However, the node certificates issued by an Auth Server are valid indefinitely by default. Teleport supports certificate rotation, i.e. the process of invalidating all previously-issued certificates for nodes *and* users regardless of their TTL. @@ -142,13 +123,9 @@ rotate`](../cli-docs.mdx#tctl-auth-rotate). When this command is invoked by a Te administrator on one of a cluster's Auth Servers, the following happens: 1. A new certificate authority (CA) key is generated. -2. The old CA will be considered valid *alongside* the new CA for some period of - time. This period of time is called a *grace period*. {/* TODO: Link to - config/defaults. */} -3. During the grace period, all previously issued certificates will be - considered valid, assuming their TTL isn't expired. -4. After the grace period is over, the certificates issued by the old CA are no - longer accepted. +2. The old CA will be considered valid *alongside* the new CA for a while. This period is called a *grace period*. {/* TODO: Link to config/defaults. */} +3. During the grace period, all previously issued certificates will be considered valid, assuming their TTL isn't expired. +4. After the grace period is over, the certificates issued by the old CA are no longer accepted. This process is repeated twice, once for the node CA and once for the user CA. @@ -161,10 +138,9 @@ learn how to do certificate rotation in practice. /* TODO: Can we say more about this, abstract of routes provided */ } -Clients can also connect to the auth API through the Teleport proxy to use a -limited subset of the API to discover the member nodes of the cluster. +Clients can also connect to the auth API through the Teleport proxy to use a limited subset of the API to discover the member nodes of the cluster. -## Auth State +## Auth state The Auth service maintains state using a database of users, credentials, certificates, and audit logs. The default storage location is @@ -173,45 +149,35 @@ destination](../admin-guide.mdx#high-availability). There are three types of data stored by the auth server: -- **Cluster State** The auth server stores its own keys in a cluster state - storage. All of cluster dynamic configuration is stored there as well, - including: +- - **Cluster State** The auth server stores its own keys in a cluster state storage. All of cluster dynamic configuration is stored there as well, including: - Node membership information and online/offline status for each node. - List of active sessions. - List of locally stored users - RBAC configuration (roles and permissions). - Other dynamic configuration. -- **Audit Log** When users log into a Teleport cluster, execute remote commands - and logout, that activity is recorded in the audit log. See Audit Log for more - details. More on this in the [Audit Log section below](#audit-log). -- **Recorded Sessions** When Teleport users launch remote shells via `tsh ssh` - command, their interactive sessions are recorded and stored by the auth - server. Each recorded session is a file which is saved in /var/lib/teleport by - default, but can also be saved in external storage, like an AWS S3 bucket. +- **Audit Log** When users log into a Teleport cluster, execute remote commands, and log out, that activity is recorded in the audit log. See Audit Log for more details. More on this in the [Audit Log section below](#audit-log). +- **Recorded Sessions** When Teleport users launch remote shells via `tsh ssh` command, their interactive sessions are recorded and stored by the auth server. Each recorded session is a file that is saved in /var/lib/teleport by default but can also be saved in external storage, like an AWS S3 bucket. -## Audit Log +## Audit log The Teleport auth server keeps the audit log of SSH-related events that take place on any node within a Teleport cluster. Each node in a cluster emits audit events and submits them to the auth server. The events recorded include: -- successful user logins -- node IP addresses -- session time -- session IDs +- Successful user logins +- Node IP addresses, Application, Database and Kubernetes FQDN +- Session time +- Session IDs - Because all SSH events like `exec` or `session_start` are by default - reported by the Teleport node service, they will not be logged if you are - using OpenSSH `sshd` daemon on your nodes. [Recording proxy mode](proxy.mdx#recording-proxy-mode) - can be used to log audit events when using OpenSSH on your nodes. + Because all SSH events like `exec` or `session_start` are by default reported by the Teleport node service, they will not be logged if you are using OpenSSH `sshd` daemon on your nodes. [Recording proxy mode](proxy.mdx#recording-proxy-mode) Only an SSH server can report what's happening to the Teleport auth server. -The audit log is a JSON file which is by default stored on the auth server's +The audit log is a JSON file that is by default stored on the auth server's filesystem under `/var/lib/teleport/log`. The format of the file is documented in the [Admin Manual](../admin-guide.mdx#audit-log). @@ -228,7 +194,7 @@ storage. same audit log. [Learn how to deploy Teleport in HA Mode.](../admin-guide.mdx#high-availability) -## Storage Back-Ends +## Storage back-ends Different types of cluster data can be configured with different storage back-ends as shown in the table below: @@ -243,13 +209,7 @@ back-ends as shown in the table below: type="tip" title="Note" > - The reason Teleport designers split the audit log events and the recorded - sessions into different back-ends is because of the nature of the data. A - recorded session is a compressed binary stream (blob) while the event is a - well-defined JSON structure. `dir` works well enough for both in small - deployments, but large clusters require specialized data stores: S3 is - perfect for uploading session blobs, while DynamoDB or `etcd` are better - suited to store the cluster state. + The reason Teleport designers split the audit log events and the recorded sessions into different back-ends is because of the nature of the data. A recorded session is a compressed binary stream (blob) while the event is a well-defined JSON structure. `dir` works well enough for both in small deployments, but large clusters require specialized data stores: S3 is perfect for uploading session blobs, while DynamoDB or `etcd` are better suited to store the cluster state. The combination of DynamoDB + S3 is especially popular among AWS users because @@ -264,7 +224,7 @@ it allows them to run Teleport clusters completely devoid of local state. configuration](../admin-guide.mdx#high-availability) in the Admin Guide. -## More Concepts +## More concepts - [Architecture Overview](overview.mdx) - [Teleport Users](users.mdx) diff --git a/docs/pages/architecture/nodes.mdx b/docs/pages/architecture/nodes.mdx index f116cfdae0347..d400bb30ba69a 100644 --- a/docs/pages/architecture/nodes.mdx +++ b/docs/pages/architecture/nodes.mdx @@ -4,36 +4,25 @@ description: This chapter explains the concept of a Teleport Node and Teleport m h1: Teleport Nodes --- -Teleport calls any computing device (server, VM, AWS intance, etc) a "node". +Teleport calls any computing device (server, VM, AWS instance, etc) a "node". -## The Node Service +## The Node service -A node becomes a Teleport Node when the node joins a cluster with a -"join" token. Read about how nodes are issued certificates in the -[Auth Guide](authentication.mdx#issuing-node-certificates). +A node becomes a Teleport Node when the node joins a cluster with a "join" token. Read about how nodes are issued certificates in the [Auth Guide](authentication.mdx#issuing-node-certificates). ![Node joins a cluster](../../img/node_join.svg) -A Teleport Node runs the [`teleport`](../cli-docs.mdx#teleport) daemon with the -`node` role. This process handles incoming connection requests, authentication, -and remote command execution on the node, similar to the function of OpenSSH's -`sshd`. +A Teleport Node runs the [`teleport`](../cli-docs.mdx#teleport) daemon with the `node` role. This process handles incoming connection requests, authentication, and remote command execution on the node, similar to the function of OpenSSH's `sshd`. ![Node Service ping API](../../img/node_service_api.svg) -All cluster Nodes keep the Auth Server updated on their status with periodic -ping messages. They report their IP addresses and values of their assigned -labels. Nodes can access the list of all Nodes in their cluster via the -[Auth Server API](authentication.mdx#auth-api). +All cluster Nodes keep the Auth Server updated on their status with periodic ping messages. They report their IP addresses and the values of their assigned labels. Nodes can access the list of all Nodes in their cluster via the [Auth Server API](authentication.mdx#auth-api). - In most environments we advise replacing the OpenSSH daemon `sshd` - with the Teleport Node Service unless there are existing workflows relying - on `ssh` or in special cases such as embedded devices that can't run - custom binaries. + In most environments, we advise replacing the OpenSSH daemon `sshd` with the Teleport Node Service unless there are existing workflows relying on `ssh` or in special cases such as embedded devices that can't run custom binaries. The `node` service provides SSH access to every node with all of the following clients: @@ -44,7 +33,7 @@ The `node` service provides SSH access to every node with all of the following c Each client is authenticated via the [Auth Service](authentication.mdx#authentication-in-teleport) before being granted access to a Node. -## Node Identity on a Cluster +## Node identity on a cluster Node Identity is defined on the Cluster level by the certificate a node possesses. @@ -58,11 +47,7 @@ This certificate contains information about the node including: - The node **role** (i.e. `node,proxy`) encoded as a certificate extension - The cert **TTL** (time-to-live) -A Teleport Cluster is a set of one or more machines whose certificates are signed -by the same certificate authority (CA) operating in the Auth Server. A -certificate is issued to a node when it joins the cluster for the first time. -Learn more about this process in the [Auth -Guide](authentication.mdx#authentication-in-teleport). +A Teleport Cluster is a set of one or more machines whose certificates are signed by the same certificate authority (CA) operating in the Auth Server. A certificate is issued to a node when it joins the cluster for the first time. Learn more about this process in the [Auth Guide](authentication.mdx#authentication-in-teleport). - In the diagram above we show each Teleport service separately for - clarity, but Teleport services do not have to run on separate nodes. - Teleport can be run as a binary on a single-node cluster with no external - storage backend. We demonstrate this minimal setup in the [Getting Started - Guide](../getting-started.mdx). + In the diagram above we show each Teleport service separately for clarity, but Teleport services do not have to run on separate nodes. + Teleport can be run as a binary on a single-node cluster with no external storage backend. We demonstrate this minimal setup in the [Getting Started Guide](../getting-started.mdx). -## Detailed Architecture Overview +## Detailed architecture overview Here is a detailed diagram of a Teleport Cluster. @@ -122,12 +113,10 @@ steps are explained in detail below the diagram. type="note" title="Caution" > - The Teleport Admin tool, `tctl` , must be physically present - on the same machine where Teleport Auth is running. Adding new nodes or - inviting new users to the cluster is only possible using this tool. + The Teleport Admin tool, `tctl`, must be physically present on the same machine where Teleport Auth is running. Adding new nodes or inviting new users to the cluster is only possible using this tool. -### 1: Initiate Client Connection +### 1: Initiate client connection ![Client offers certificate](../../img/client_initiate.svg) @@ -142,7 +131,7 @@ its certificate. Clients must always connect through a proxy for two reasons: This makes it possible for an SSH user to see if someone else is connected to a node she is about to work on. -### 2: Authenticate Client Certificate +### 2: Authenticate client certificate ![Client offers valid certificate](../../img/cert_ok.svg) @@ -151,8 +140,7 @@ auth server. ![Client obtains new certificate](../../img/cert_invalid.svg) -If there was no certificate previously offered (first time login) or if the -certificate has expired, the proxy denies the connection and asks the client to +If there was no certificate previously offered (first time log in) or if the certificate has expired, the proxy denies the connection and asks the client to login interactively using a password and a 2nd factor if enabled. Teleport supports @@ -184,9 +172,8 @@ At this step, the proxy tries to locate the requested node in a cluster. There are three lookup mechanisms a proxy uses to find the node's IP address: 1. Uses DNS to resolve the name requested by the client. -2. Asks the Auth Server if there is a Node registered with this `nodename` . -3. Asks the Auth Server to find a node (or nodes) with a label that matches the - requested name. +2. Asks the Auth Server if there is a Node registered with this `nodename`. +3. Asks the Auth Server to find a node (or nodes) with a label that matches the requested name. If the node is located, the proxy establishes the connection between the client and the requested node. The destination node then begins recording the session, @@ -201,7 +188,7 @@ sending the session history to the auth server to be stored. information. -### 4: Authenticate Node Certificate +### 4: Authenticate Node certificate ![Node Membership Authentication](../../img/node_cluster_auth.svg) @@ -211,7 +198,7 @@ validate the node's certificate and validate the Node's cluster membership. If the node certificate is valid, the node is allowed to access the Auth Server API which provides access to information about nodes and users in the cluster. -### 5: Grant User Node Access +### 5: Grant user Node access ![User Granted Node Access](../../img/user_node_access.svg) @@ -223,19 +210,19 @@ Finally, the client is authorized to create an SSH connection to a node. ![Proxy Connection Established](../../img/proxy_client_connect.svg) -## Teleport CLI Tools +## Teleport CLI tools -Teleport offers two command line tools. `tsh` is a client tool used by the end +Teleport offers two command-line tools. `tsh` is a client tool used by the end users, while `tctl` is used for cluster administration. ### TSH -`tsh` is similar in nature to OpenSSH `ssh` or `scp`. In fact, it has +`tsh` is similar in nature to OpenSSH `ssh` or `scp`. It has subcommands named after them so you can call: -```bsh -$ tsh --proxy=p ssh -p 1522 user@host -$ tsh --proxy=p scp -P example.txt user@host/destination/dir +```bash +tsh --proxy=p ssh -p 1522 user@host +tsh --proxy=p scp -P example.txt user@host/destination/dir ``` Unlike `ssh`, `tsh` is very opinionated about authentication: it always uses @@ -253,12 +240,12 @@ You can learn more about `tsh` in the [User Manual](../user-manual.mdx). server listening on `127.0.0.1` and allows a cluster administrator to manage nodes and users in the cluster. -`tctl` is also a tool which can be used to modify the dynamic configuration of +`tctl` is also a tool that can be used to modify the dynamic configuration of the cluster, like creating new user roles or connecting trusted clusters. You can learn more about `tctl` in the [Admin Manual](../admin-guide.mdx). -## Next Steps +## Next steps - If you haven't already, read the [Getting Started Guide](../getting-started.mdx) to run a minimal setup of Teleport yourself. diff --git a/docs/pages/architecture/proxy.mdx b/docs/pages/architecture/proxy.mdx index 774b4d7f20d8c..373f9e0ca59fd 100644 --- a/docs/pages/architecture/proxy.mdx +++ b/docs/pages/architecture/proxy.mdx @@ -4,7 +4,7 @@ description: How Teleport implements SSH and Kubernetes access via a Proxy h1: The Proxy Service --- -The proxy is a stateless service which performs three main functions in a +The proxy is a stateless service that performs three main functions in a Teleport cluster: 1. It serves as an authentication gateway. It asks for credentials from @@ -12,7 +12,7 @@ Teleport cluster: API](authentication.mdx#auth-api). 2. It looks up the IP address for a requested Node and then proxies a connection from client to Node. -3. It serves a Web UI which is used by cluster users to sign up and configure +3. It serves a Web UI that is used by cluster users to sign up and configure their accounts, explore Nodes in a cluster, log into remote Nodes, join existing SSH sessions or replay recorded sessions. @@ -25,18 +25,12 @@ client SSH connection: ![Teleport Proxy Web](../../img/proxy-web.svg) -1. User logs in to Web UI using username and password, and 2nd factor token if - configured (2FA Tokens are not used with SSO providers). +1. User logs in to Web UI using username and password, and 2nd-factor token if configured (2FA Tokens are not used with SSO providers). 2. Proxy passes credentials to the Auth Server's API -3. If Auth Server accepts credentials, it generates a new web session and - generates a special ssh keypair associated with this web session. Auth server - starts serving [OpenSSH ssh-agent - protocol](https://tools.ietf.org/html/draft-miller-ssh-agent-04) - to the proxy. -4. The User obtains an SSH session in the Web UI and can interact with the Node - on a web-based terminal. From the Node's perspective, it's a regular SSH - client connection that is authenticated using an OpenSSH certificate, so no - special logic is needed. +3. If Auth Server accepts credentials, it generates a new web session and generates a special ssh keypair associated with this web session. Auth server + starts serving [OpenSSH ssh-agent protocol](https://tools.ietf.org/html/draft-miller-ssh-agent-04) to the proxy. +4. The User obtains an SSH session in the Web UI and can interact with the Node on a web-based terminal. From the Node's perspective, it's a regular SSH + client connection that is authenticated using an OpenSSH certificate, so no special logic is needed. -## Recording Proxy Mode +## Recording Proxy mode In this mode, the proxy terminates (decrypts) the SSH connection using the certificate supplied by the client via SSH agent forwarding and then establishes @@ -118,11 +104,8 @@ We consider the "recording proxy mode" to be less secure for two reasons: the proxy stores no secrets and cannot "see" the decrypted data. This makes a proxy less critical to the security of the overall cluster. But if an attacker gains physical access to a proxy Node running in the "recording" - mode, they will be able to see the decrypted traffic and client keys stored - in proxy's process memory. -2. Recording proxy mode requires the SSH agent forwarding. Agent forwarding is - required because without it, a proxy will not be able to establish the 2nd - connection to the destination Node. + mode, they will be able to see the decrypted traffic and client keys stored in the proxy's process memory. +2. Recording proxy mode requires SSH Agent Forwarding. Agent Forwarding is required because without it, a proxy will not be able to establish the 2nd connection to the destination Node. However, there are advantages of proxy-based session recording too. When sessions are recorded at the Nodes, a root user can add iptables rules to @@ -134,7 +117,7 @@ See the [admin guide](../admin-guide.mdx#recorded-sessions) to learn how to turn on the recording proxy mode. Note that the recording mode is configured on the Auth Service. -## More Concepts +## More concepts - [Architecture Overview](overview.mdx) - [Teleport Users](users.mdx) diff --git a/docs/pages/architecture/users.mdx b/docs/pages/architecture/users.mdx index 994767d351135..f4c9ca999fd8e 100644 --- a/docs/pages/architecture/users.mdx +++ b/docs/pages/architecture/users.mdx @@ -8,22 +8,14 @@ h1: Teleport Users /* TODO: This doc is incomplete, pending addition of Enterprise topics */ } -## Types of Users +## Types of users -Unlike traditional SSH, Teleport introduces the concept of a User Account. A -User Account is not the same as SSH login. Instead each Teleport User is -associated with another account which is used to authenticate the user. +Unlike traditional SSH, Teleport introduces the concept of a User Account. A User Account is not the same as SSH login. Instead, each Teleport User is associated with another account which is used to authenticate the user. -For Open Source edition users, these will be OS users which are administered -outside of Teleport on each cluster node. For example, there can be a Teleport -user "joe" who can be given permission to login as "root" to a specific subset -of nodes. Another user "juliet" could be given permission to OS users "root" and -to "nginx". Teleport does not have knowledge of the OS Users so it expects both -"root" and "nginx" to exist on the node. +For Open Source edition users, these will be OS users who are administered +outside of Teleport on each cluster node. For example, there can be a Teleport user `joe` who can be permitted to log in as "root" to a specific subset of nodes. Another user `juliet` could be permitted to OS users `root` and to `nginx`. Teleport does not know the OS Users so it expects both `root` and `nginx` to exist on the node. -For Enterprise edition users, these can be stored in an external identity -sources such as OKTA, Active Directory, OneLogin, G Suite, or OIDC. Read the -[Enterprise Guide](../enterprise/introduction.mdx) to learn more. +For Enterprise edition users, these can be stored in an external identity source such as OKTA, Active Directory, OneLogin, G Suite, or OIDC. Read the [Enterprise Guide](../enterprise/introduction.mdx) to learn more. Teleport supports two types of user accounts: **Local Users** and **External Users**. @@ -37,18 +29,16 @@ Let's look at this table: | Teleport User | Allowed OS Logins | Description | | - | - | - | -| joe | joe, root | Teleport user 'joe' can login into member nodes as OS user 'joe' or 'root' | -| juliet | juliet | Teleport user 'juliet' can login into member nodes only as OS user 'juliet' | -| ross | | If no OS login is specified, it defaults to the same name as the Teleport user, here this is "ross". | +| joe | joe, root | Teleport user `joe` can log in into member nodes as OS user `joe` or `root`. | +| juliet | juliet | Teleport user `juliet` can log in into member nodes only as OS user `juliet`. | +| ross | | If no OS login is specified, it defaults to the same name as the Teleport user, here this is `ross`. | To add a new user to Teleport, you have to use the `tctl` tool on the same node where the auth server is running, i.e. `teleport` was started with `--roles=auth` . A cluster administrator must create account entries for every Teleport user with -[`tctl users add`](../cli-docs.mdx). Every Teleport User must be associated with a -list of one or more machine-level OS usernames it can authenticate as during a -login. This list is called "user mappings". +[`tctl users add`](../cli-docs.mdx). Every Teleport User must be associated with a list of one or more machine-level OS usernames it can authenticate as during a login. This list is called "user mappings". ![User Mappings](../../img/user_mappings.svg) @@ -67,7 +57,7 @@ from this example: | teleport | teleport | grav-00, grav-02 | | sandra | ops | grav-00, grav-01 | -Teleport supports second factor authentication (2FA) when using a local auth +Teleport supports second-factor authentication (2FA) when using a local auth connector and it is enforced by default. -#### Multiple Identity Sources +#### Multiple identity sources -It is possible to have multiple identity sources configured for a Teleport -cluster. In this case, an identity source (called a "connector") will have to be -passed to [`tsh --auth=connector_name login`](../cli-docs.mdx#tsh-login). +It is possible to have multiple identity sources configured for a Teleport cluster. In this case, an identity source (called a "connector") will have to be passed to [`tsh --auth=connector_name login`](../cli-docs.mdx#tsh-login). { /* TODO: Production Configuration */ @@ -120,18 +108,15 @@ passed to [`tsh --auth=connector_name login`](../cli-docs.mdx#tsh-login). The local users connector can be specified via [`tsh --auth=local login`](../cli-docs.mdx#tsh-login). -## User Roles +## User roles -Unlike traditional SSH, each Teleport user account is assigned a `role` . Having -roles allows Teleport to implement role-based access control (RBAC), i.e. assign -users to groups (roles) and restrict each role to a subset of actions on a -subset of nodes in a cluster. +Unlike traditional SSH, each Teleport user account is assigned a `role`. Having roles allows Teleport to implement role-based access control (RBAC), i.e. assign users to groups (roles) and restrict each role to a subset of actions on a subset of nodes in a cluster. { /* TODO: Enterprise Topic */ } -## More Concepts +## More concepts - [Architecture Overview](overview.mdx) - [Teleport Auth](authentication.mdx) diff --git a/docs/pages/config-reference.mdx b/docs/pages/config-reference.mdx index 64c83284fbc8f..5aebd9356e825 100644 --- a/docs/pages/config-reference.mdx +++ b/docs/pages/config-reference.mdx @@ -9,6 +9,8 @@ Teleport uses the YAML file format for configuration. A full configuration refer file is shown below, this provides comments and all available options for `teleport.yaml` By default, it is stored in `/etc/teleport.yaml`. +(!docs/pages/includes/backup-warning.mdx!) + This document aims to be a reference rather than a starting point for a real cluster. To get a good starting file, run `teleport configure -o teleport.yaml`. diff --git a/docs/pages/includes/backup-warning.mdx b/docs/pages/includes/backup-warning.mdx new file mode 100644 index 0000000000000..96c17bda6c3c4 --- /dev/null +++ b/docs/pages/includes/backup-warning.mdx @@ -0,0 +1,3 @@ + + Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed. + \ No newline at end of file diff --git a/docs/pages/includes/permission-warning.mdx b/docs/pages/includes/permission-warning.mdx new file mode 100644 index 0000000000000..b3f5f5b1eab8b --- /dev/null +++ b/docs/pages/includes/permission-warning.mdx @@ -0,0 +1,12 @@ + + The examples below may include the use of the `sudo` keyword, token UUIDs, and users with `admin` privileges to make following each step easier when creating resources from scratch. + + Generally: + + 1. We discourage using `sudo` in production environments unless it's needed. + 2. We encourage creating new, non-root, users or new test instances for experimenting with Teleport. + 3. We encourage adherence to the *Principle of Least Privilege* (PoLP) and *Zero Admin* best practices. Don't give users the `admin` role when giving them the more restrictive `access,editor` roles will do instead. + 4. Saving tokens into a file rather than sharing tokens directly *as strings*. + + Learn more about [Teleport Role-Based Access Control](https://goteleport.com/docs/access-controls/introduction/) best practices. + \ No newline at end of file diff --git a/docs/pages/metrics-logs-reference.mdx b/docs/pages/metrics-logs-reference.mdx index 79c315ebf10b6..1e15fbed1e554 100644 --- a/docs/pages/metrics-logs-reference.mdx +++ b/docs/pages/metrics-logs-reference.mdx @@ -28,30 +28,30 @@ Now you can see the monitoring information by visiting several endpoints: | Name | Type | Component | Description | | - | - | - | - | -| `backend_batch_read_requests_total` | counter | cache | Number of read requests to the backend | -| `backend_batch_read_seconds` | histogram | cache | Latency for batch read operations | -| `backend_batch_write_requests_total` | counter | cache | Number of batch write requests to the backend | -| `backend_batch_write_seconds` | histogram | cache | Latency for backend batch write operations | -| `backend_read_requests_total` | counter | cache | Number of read requests to the backend | -| `backend_read_seconds` | histogram | cache | Latency for read operations | -| `backend_write_requests_total` | counter | cache | Number of write requests to the backend | -| `backend_write_seconds` | histogram | cache | Latency for backend write operations | -| `etcd_backend_batch_read_requests` | counter | etcd | Number of read requests to the etcd database | -| `etcd_backend_batch_read_seconds` | histogram | etcd | Latency for etcd read operations | -| `etcd_backend_read_requests` | counter | etcd | Number of read requests to the etcd database | -| `etcd_backend_read_seconds` | histogram | etcd | Latency for etcd read operations | -| `etcd_backend_tx_requests` | counter | etcd | Number of transaction requests to the database | -| `etcd_backend_tx_seconds` | histogram | etcd | Latency for etcd transaction operations | -| `etcd_backend_write_requests` | counter | etcd | Number of write requests to the database | -| `etcd_backend_write_seconds` | histogram | etcd | Latency for etcd write operations | -| `firestore_events_backend_batch_read_requests` | counter | GCP Cloud Firestore | Number of batch read requests to Cloud Firestore events | -| `firestore_events_backend_batch_read_seconds` | histogram | GCP Cloud Firestore | Latency for Cloud Firestore events batch read operations | -| `firestore_events_backend_batch_write_requests` | counter | GCP Cloud Firestore | Number of batch write requests to Cloud Firestore events | -| `firestore_events_backend_batch_write_seconds` | histogram | GCP Cloud Firestore | Latency for Cloud Firestore events batch write operations | -| `gcs_event_storage_downloads` | counter | GCP GCS | Number of downloads from the GCS backend | -| `gcs_event_storage_downloads_seconds` | histogram | Internal GoLang | Latency for GCS download operations | -| `gcs_event_storage_uploads` | counter | Internal GoLang | Number of uploads to the GCS backend | -| `gcs_event_storage_uploads_seconds` | histogram | Internal GoLang | Latency for GCS upload operations | +| `backend_batch_read_requests_total` | counter | cache | Number of read requests to the backend. | +| `backend_batch_read_seconds` | histogram | cache | Latency for batch read operations. | +| `backend_batch_write_requests_total` | counter | cache | Number of batch write requests to the backend. | +| `backend_batch_write_seconds` | histogram | cache | Latency for backend batch write operations. | +| `backend_read_requests_total` | counter | cache | Number of read requests to the backend. | +| `backend_read_seconds` | histogram | cache | Latency for read operations. | +| `backend_write_requests_total` | counter | cache | Number of write requests to the backend. | +| `backend_write_seconds` | histogram | cache | Latency for backend write operations. | +| `etcd_backend_batch_read_requests` | counter | etcd | Number of read requests to the etcd database. | +| `etcd_backend_batch_read_seconds` | histogram | etcd | Latency for etcd read operations. | +| `etcd_backend_read_requests` | counter | etcd | Number of read requests to the etcd database. | +| `etcd_backend_read_seconds` | histogram | etcd | Latency for etcd read operations. | +| `etcd_backend_tx_requests` | counter | etcd | Number of transaction requests to the database. | +| `etcd_backend_tx_seconds` | histogram | etcd | Latency for etcd transaction operations. | +| `etcd_backend_write_requests` | counter | etcd | Number of write requests to the database. | +| `etcd_backend_write_seconds` | histogram | etcd | Latency for etcd write operations. | +| `firestore_events_backend_batch_read_requests` | counter | GCP Cloud Firestore | Number of batch read requests to Cloud Firestore events. | +| `firestore_events_backend_batch_read_seconds` | histogram | GCP Cloud Firestore | Latency for Cloud Firestore events batch read operations. | +| `firestore_events_backend_batch_write_requests` | counter | GCP Cloud Firestore | Number of batch write requests to Cloud Firestore events. | +| `firestore_events_backend_batch_write_seconds` | histogram | GCP Cloud Firestore | Latency for Cloud Firestore events batch write operations. | +| `gcs_event_storage_downloads` | counter | GCP GCS | Number of downloads from the GCS backend. | +| `gcs_event_storage_downloads_seconds` | histogram | Internal GoLang | Latency for GCS download operations. | +| `gcs_event_storage_uploads` | counter | Internal GoLang | Number of uploads to the GCS backend. | +| `gcs_event_storage_uploads_seconds` | histogram | Internal GoLang | Latency for GCS upload operations. | | `go_gc_duration_seconds` | summary | Internal GoLang | A summary of the GC invocation durations. | | `go_goroutines` | gauge | Internal GoLang | Number of goroutines that currently exist. | | `go_info` | gauge | Internal GoLang | Information about the Go environment. | @@ -91,23 +91,23 @@ Now you can see the monitoring information by visiting several endpoints: | `promhttp_metric_handler_requests_total` | counter | prometheus | Total number of scrapes by HTTP status code. | | `reversetunnel_connected_proxies` | gauge | Teleport | Number of known proxies being sought. | | `rx` | counter | Teleport | Number of bytes received. | -| `server_interactive_sessions_total` | gauge | Teleport | Number of active sessions | -| `trusted_clusters` | gauge | Teleport | Number of tunnels per state | +| `server_interactive_sessions_total` | gauge | Teleport | Number of active sessions. | +| `trusted_clusters` | gauge | Teleport | Number of tunnels per state. | | `tx` | counter | Teleport | Number of bytes transmitted. | | `audit_failed_disk_monitoring` | counter | Teleport Audit Log | Number of times disk monitoring failed. | | `audit_failed_emit_events` | counter | Teleport Audit Log | Number of times emitting audit event failed. | | `audit_percentage_disk_space_used` | gauge | Teleport Audit Log | Percentage disk space used. | -| `audit_server_open_files` | gauge | Teleport Audit Log | Number of open audit files | -| `auth_generate_requests` | gauge | Teleport Auth | Number of current generate requests | -| `auth_generate_requests_throttled_total` | counter | Teleport Auth | Number of throttled requests to generate new server keys | -| `auth_generate_requests_total` | counter | Teleport Auth | Number of requests to generate new server keys | -| `auth_generate_seconds` | `histogram` | Teleport Auth | Latency for generate requests | -| `cluster_name_not_found_total` | counter | Teleport Auth | Number of times a cluster was not found | -| `heartbeat_connections_received_total` | counter | Teleport Auth | Number of times auth received a heartbeat connection | -| `heartbeat_connections_missed_total` | counter | Teleport Auth | Number of times auth did not receive a heartbeat from a node | -| `user_login_total` | counter | Teleport Auth | Number of user logins | +| `audit_server_open_files` | gauge | Teleport Audit Log | Number of open audit files. | +| `auth_generate_requests` | gauge | Teleport Auth | Number of current generate requests. | +| `auth_generate_requests_throttled_total` | counter | Teleport Auth | Number of throttled requests to generate new server keys. | +| `auth_generate_requests_total` | counter | Teleport Auth | Number of requests to generate new server keys. | +| `auth_generate_seconds` | `histogram` | Teleport Auth | Latency for generate requests. | +| `cluster_name_not_found_total` | counter | Teleport Auth | Number of times a cluster was not found. | +| `heartbeat_connections_received_total` | counter | Teleport Auth | Number of times auth received a heartbeat connection. | +| `heartbeat_connections_missed_total` | counter | Teleport Auth | Number of times auth did not receive a heartbeat from a node. | +| `user_login_total` | counter | Teleport Auth | Number of user logins. | | `failed_connect_to_node_attempts_total` | counter | Teleport Proxy | Number of times a user failed connecting to a node | -| `proxy_connection_limit_exceeded_total` | counter | Teleport Proxy | Number of connections that exceeded the proxy connection limit | -| `certificate_mismatch_total` | counter | Teleport Proxy | Number of times there was a certificate mismatch | -| `failed_login_attempts_total` | counter | Teleport Proxy | Number of failed `tsh login` or `tsh ssh` logins | -| `user_max_concurrent_sessions_hit_total` | counter | Teleport Node | Number of times a user exceeded their concurrent session limit | +| `proxy_connection_limit_exceeded_total` | counter | Teleport Proxy | Number of connections that exceeded the proxy connection limit. | +| `certificate_mismatch_total` | counter | Teleport Proxy | Number of times there was a certificate mismatch. | +| `failed_login_attempts_total` | counter | Teleport Proxy | Number of failed `tsh login` or `tsh ssh` logins. | +| `user_max_concurrent_sessions_hit_total` | counter | Teleport Node | Number of times a user exceeded their concurrent session limit. | diff --git a/docs/pages/trustedclusters.mdx b/docs/pages/trustedclusters.mdx index 603a3129f7435..d7f6d82f1eefd 100644 --- a/docs/pages/trustedclusters.mdx +++ b/docs/pages/trustedclusters.mdx @@ -1,28 +1,28 @@ --- title: Teleport Trusted Clusters -description: How to configure access and trust between two SSH and Kubernetes environments +description: How to configure access and trust between two SSH and Kubernetes environments. h1: Trusted Clusters --- The design of trusted clusters allows Teleport users to connect to compute infrastructure -located behind firewalls without any open TCP ports. The real world usage examples of this +located behind firewalls without any open TCP ports. The real-world usage examples of this capability include: -- Managed service providers (MSP) remotely managing infrastructure of their clients. -- Device manufacturers remotely maintaining computing appliances deployed on premises. +- Managed service providers (MSP) remotely managing the infrastructure of their clients. +- Device manufacturers remotely maintaining computing appliances deployed on-premises. - Large cloud software vendors manage multiple data centers using a common proxy. **Example of a MSP provider using trusted cluster to obtain access to clients clusters.** ![MSP Example](../img/trusted-clusters/TrustedClusters-MSP.svg) If you haven't already looked at the introduction to [Trusted Clusters](admin-guide.mdx#trusted-clusters) -in the Admin Guide we recommend you review that for an overview before continuing with this guide. +in the Admin Guide, we recommend you review that for an overview before continuing with this guide. The Trusted Clusters chapter in the Admin Guide offers an example of a simple configuration which: - Uses a static cluster join token defined in a configuration file. -- Does not cover inter-cluster role based access control (RBAC). +- Does not cover inter-cluster Role-Based Access Control (RBAC). This guide's focus is on more in-depth coverage of trusted clusters features and will cover the following topics: @@ -34,9 +34,7 @@ This guide's focus is on more in-depth coverage of trusted clusters features and type="tip" title="Teleport Node Tunneling" > - If you have a large amount of devices on different networks, such as - managed IoT devices or a couple of nodes on a different network you can utilize - the [Teleport Node Tunneling](admin-guide.mdx#adding-a-node-located-behind-nat). + If you have a large number of devices on different networks, such as managed IoT devices or a couple of nodes on a different network you can utilize the [Teleport Node Tunneling](admin-guide.mdx#adding-a-node-located-behind-nat). ## Introduction @@ -52,31 +50,34 @@ clusters, they would normally have to use different `--proxy` flags for each cluster. This is not always convenient. The concept of *leaf clusters* allows Teleport administrators to connect -multiple clusters together and establish trust between them. Trusted clusters +multiple clusters and establish trust between them. Trusted clusters allow users of one cluster, the root cluster to seamlessly SSH into the nodes of another cluster without having to "hop" between proxy servers. Moreover, users don't -even need to have a direct connection to other clusters' proxy servers. The user -experience looks like this: +even need to have a direct connection to other clusters' proxy servers. -```bsh -# login using the root "root" cluster credentials: -$ tsh login --proxy=root.example.com +(!docs/pages/includes/permission-warning.mdx!) + +The user experience looks like this: + +```bash +# Log in using the root "root" cluster credentials: +tsh login --proxy=root.example.com # SSH into some host inside the "root" cluster: -$ tsh ssh host +tsh ssh host # SSH into the host located in another cluster called "leaf" # The connection is established through root.example.com: -$ tsh ssh --cluster=leaf host +tsh ssh --cluster=leaf host # See what other clusters are available -$ tsh clusters +tsh clusters ``` Leaf clusters also have their own restrictions on user access, i.e. *permissions mapping* takes place. -**Once connection has been established it's easy to switch from the "root" root cluster** +**Once a connection has been established it's easy to switch from the "root" root cluster** ![Teleport Cluster Page](../img/trusted-clusters/teleport-trusted-cluster.png) Let's take a look at how a connection is established between the "root" cluster @@ -86,24 +87,16 @@ and the "leaf" cluster: This setup works as follows: -1. The "leaf" creates an outbound reverse SSH tunnel to "root" and keeps the - tunnel open. -2. **Accessibility only works in one direction.** The "leaf" cluster allows - users from "root" to access its nodes but users in the "leaf" cluster can not - access the "root" cluster. -3. When a user tries to connect to a node inside "leaf" using root's proxy, the - reverse tunnel from step 1 is used to establish this connection shown as the - green line above. +1. The "leaf" creates an outbound reverse SSH tunnel to "root" and keeps the tunnel open. +2. **Accessibility only works in one direction.** The "leaf" cluster allows users from "root" to access its nodes but users in the "leaf" cluster can not access the "root" cluster. +3. When a user tries to connect to a node inside "leaf" using the root's proxy, the reverse tunnel from step 1 is used to establish this connection shown as the green line above. - The scheme above also works even if the "root" cluster uses multiple - proxies behind a load balancer (LB) or a DNS entry with multiple values. - This works by "leaf" establishing a tunnel to *every* proxy in "root". This - requires that an LB uses round-robin or a similar balancing algorithm. Do - not use sticky load balancing algorithms (a.k.a. "session affinity" or "sticky sessions") with + The scheme above also works even if the "root" cluster uses multiple proxies behind a load balancer (LB) or a DNS entry with multiple values. + This works by "leaf" establishing a tunnel to *every* proxy in "root". This requires that an LB uses a round-robin or a similar balancing algorithm. Do not use sticky load balancing algorithms (a.k.a. "session affinity" or "sticky sessions") with Teleport proxies. @@ -113,21 +106,16 @@ Lets start with the diagram of how connection between two clusters is establishe ![Tunnels](../img/trusted-clusters/TrustedClusters-Simple.svg) -The first step in establishing a secure tunnel between two clusters is for the -*leaf* cluster "leaf" to connect to the *root* cluster "root". When this -happens for *the first time*, clusters know nothing about each other, thus a -shared secret needs to exist in order for "root" to accept the connection from -"leaf". +The first step in establishing a secure tunnel between two clusters is for the *leaf* cluster "leaf" to connect to the *root* cluster "root". When this +happens for *the first time*, clusters know nothing about each other, thus a shared secret needs to exist for "root" to accept the connection from "leaf". -This shared secret is called a "join token". There are two ways to create join -tokens: to statically define them in a configuration file, or to create them on -the fly using `tctl` tool. +This shared secret is called a "join token". There are two ways to create join tokens: to statically define them in a configuration file or to create them on the fly using `tctl` tool. - It's important to note that join tokens are only used to establish the connection for the first time. The clusters will exchange certificates and won't use tokens to re-establish their connection afterwards. + It's important to note that join tokens are only used to establish the connection for the first time. The clusters will exchange certificates and won't use tokens to re-establish their connection afterward. ### Static Join Tokens @@ -147,37 +135,33 @@ auth_service: This token can be used an unlimited number of times. -### Security Implications +### Security implications -Consider the security implications when deciding which token method to use. -Short lived tokens decrease the window for attack, but will require any automation -which uses these tokens to refresh them on a regular basis. +Consider the security implications when deciding which token method to use. Short-lived tokens decrease the window for an attack but will require any automation which uses these tokens to refresh them regularly. ### Dynamic Join Tokens -Creating a token dynamically with a CLI tool offers the advantage of applying a -time to live (TTL) interval on it, i.e. it will be impossible to re-use such -token after a specified period of time. +Creating a token dynamically with a CLI tool offers the advantage of applying a time-to-live (TTL) interval on it, i.e. it will be impossible to re-use such token after a specified time. To create a token using the CLI tool, execute this command on the *auth server* of cluster "root": -```bsh -# generates a trusted cluster token to allow an inbound connection from a leaf cluster: -$ tctl tokens add --type=trusted_cluster --ttl=5m -# Example output +```bash +# Generates a trusted cluster token to allow an inbound connection from a leaf cluster: +tctl tokens add --type=trusted_cluster --ttl=5m +# Example output: # The cluster invite token: ba4825847f0378bcdfe18113c4998498 # This token will expire in 5 minutes -# generates a trusted cluster token with labels: +# Generates a trusted cluster token with labels: # every cluster joined using this token will inherit env:prod labels. -$ tctl tokens add --type=trusted_cluster --labels=env=prod +tctl tokens add --type=trusted_cluster --labels=env=prod -# you can also list the outstanding non-expired tokens: -$ tctl tokens ls +# You can also list the outstanding non-expired tokens: +tctl tokens ls # ... or delete/revoke an invitation: -$ tctl tokens rm ba4825847f0378bcdfe18113c4998498 +tctl tokens rm ba4825847f0378bcdfe18113c4998498 ``` Users of Teleport will recognize that this is the same way you would add any @@ -191,21 +175,21 @@ Now, the administrator of "leaf" must create the following resource file: kind: trusted_cluster version: v2 metadata: - # the trusted cluster name MUST match the 'cluster_name' setting of the + # The trusted cluster name MUST match the 'cluster_name' setting of the # root cluster name: root spec: - # this field allows to create tunnels that are disabled, but can be enabled later. + # This field allows to create tunnels that are disabled, but can be enabled later. enabled: true - # the token expected by the "root" cluster: + # The token expected by the "root" cluster: token: ba4825847f0378bcdfe18113c4998498 - # the address in 'host:port' form of the reverse tunnel listening port on the + # The address in 'host:port' form of the reverse tunnel listening port on the # "root" proxy server: tunnel_addr: root.example.com:3024 - # the address in 'host:port' form of the web listening port on the + # The address in 'host:port' form of the web listening port on the # "root" proxy server: - web_proxy_addr: root.example.com:3080 - # the role mapping allows to map user roles from one cluster to another + web_proxy_addr: root.example.com:443 + # The role mapping allows to map user roles from one cluster to another # (enterprise editions of Teleport only) role_map: - remote: "admin" # users who have "admin" role on "root" @@ -215,20 +199,17 @@ spec: Then, use `tctl create` to add the file: ```bash -$ tctl create cluster.yaml +tctl create cluster.yaml ``` -At this point the users of the "root" cluster should be able to see "leaf" in the list of available clusters. +At this point, the users of the "root" cluster should be able to see "leaf" in the list of available clusters. - If the `web_proxy_addr` endpoint of the root - cluster uses a self-signed or invalid HTTPS certificate, you will get an - error: *"the trusted cluster uses misconfigured HTTP/TLS certificate"*. For - ease of testing, the Teleport daemon on "leaf" can be started with the - `--insecure` CLI flag to accept self-signed certificates. Make sure to configure + If the `web_proxy_addr` endpoint of the root cluster uses a self-signed or invalid HTTPS certificate, you will get an error: *"the trusted cluster uses misconfigured HTTP/TLS certificate"*. For + ease of testing, the Teleport daemon on "leaf" can be started with the `--insecure` CLI flag to accept self-signed certificates. Make sure to configure HTTPS properly and remove the insecure flag for production use. @@ -238,37 +219,33 @@ At this point the users of the "root" cluster should be able to see "leaf" in th type="warning" title="Version Warning" > - The RBAC section is applicable only to Teleport Enterprise. The open source - version does not support SSH roles. + The RBAC section is applicable only to Teleport Enterprise. Teleport Open Source does not support SSH roles. When a *leaf* cluster "leaf" from the diagram above establishes trust with the *root* cluster "root", it needs a way to configure which users from "root" should be allowed in and what permissions should they have. Teleport offers -two methods of limiting access, by using role mapping or cluster labels. +two methods of limiting access, by using role mapping of cluster labels. Consider the following: - Both clusters "root" and "leaf" have their own locally defined roles. - Every user in Teleport Enterprise is assigned a role. -- When creating a *trusted cluster* resource, the administrator of "leaf" must - define how roles from "root" map to roles on "leaf". -- To update role map for an existing *trusted cluster* delete and re-create the *trusted cluster* with the updated role map +- When creating a *trusted cluster* resource, the administrator of "leaf" must define how roles from "root" map to roles on "leaf". +- To update the role map for an existing *trusted cluster* delete and re-create the *trusted cluster* with the updated role map. ### Example -Lets make a few assumptions for this example: +Let's make a few assumptions for this example: -- The cluster "root" has two roles: *user* for regular users and *admin* for - local administrators. -- We want administrators from "root" (but not regular users!) to have - restricted access to "leaf". We want to deny them access to machines +- The cluster "root" has two roles: *user* for regular users and *admin* for local administrators. +- We want administrators from "root" (but not regular users!) to have restricted access to "leaf". We want to deny them access to machines with "environment=production" and any Government cluster labeled "customer=gov" First, we need to create a special role for root users on "leaf": ```yaml -# save this into root-user-role.yaml on the leaf cluster and execute: +# Save this into root-user-role.yaml on the leaf cluster and execute: # tctl create root-user-role.yaml kind: role version: v3 @@ -281,12 +258,12 @@ spec: # Cluster labels control what clusters user can connect to. The wildcard ('*') means # any cluster. If no role in the role set is using labels and the cluster is not labeled, # the cluster labels check is not applied. Otherwise, cluster labels are always enforced. - # This makes the feature backwards-compatible. + # This makes the feature backward-compatible. cluster_labels: 'env': 'staging' deny: - # cluster labels control what clusters user can connect to. The wildcard ('*') means - # any cluster. By default none is set in deny rules to preserve backwards compatibility + # Cluster labels control what clusters user can connect to. The wildcard ('*') means + # any cluster. By default none is set in deny rules to preserve backward compatibility cluster_labels: 'customer': 'gov' node_labels: @@ -298,7 +275,7 @@ done by creating a trusted cluster [resource](admin-guide.mdx#resources) on "lea which looks like this: ```yaml -# save this as root-cluster.yaml on the auth server of "leaf" and then execute: +# Save this as root-cluster.yaml on the auth server of "leaf" and then execute: # tctl create root-cluster.yaml kind: trusted_cluster version: v1 @@ -317,7 +294,7 @@ spec: ``` What if we wanted to let *any* user from "root" to be allowed to connect to -nodes on "leaf"? In this case we can use a wildcard `*` in the `role_map` like this: +nodes on "leaf"? In this case, we can use a wildcard `*` in the `role_map` like this: ```yaml role_map: @@ -336,7 +313,7 @@ map user roles from one cluster to another, you can even capture parts of the re role name and use reference it to name the local role: ```yaml - # in this example, remote users with remote role called 'remote-one' will be + # In this example, remote users with a remote role called 'remote-one' will be # mapped to a local role called 'local-one', and `remote-two` becomes `local-two`, etc: - remote: "^remote-(.*)$" local: [local-$1] @@ -353,21 +330,21 @@ Teleport Proxy UI. **Creating Trust from the Leaf node to the root node.** ![Tunnels](../img/trusted-clusters/setting-up-trust.png) -## Updating Trusted Cluster Role Map +## Updating Trusted Cluster role map -In order to update the role map for a trusted cluster, first we will need to remove the cluster by executing: +To update the role map for a trusted cluster, first, we'll need to remove the cluster by executing: -```bsh -$ tctl rm tc/root-cluster +```bash +tctl rm tc/root-cluster ``` Then following updating the role map, we can re-create the cluster by executing: -```bsh -$ tctl create root-user-updated-role.yaml +```bash +tctl create root-user-updated-role.yaml ``` -### Updating Cluster Labels +### Updating cluster labels Teleport gives administrators of root clusters the ability to control cluster labels. Allowing leaf clusters to propagate their own labels could create a problem with @@ -377,71 +354,78 @@ An administrator of a root cluster can control a remote/leaf cluster's labels using the remote cluster API without any fear of override: ```bash -$ tctl get rc - -kind: remote_cluster -metadata: - name: two -status: - connection: online - last_heartbeat: "2020-09-14T03:13:59.35518164Z" -version: v3 +tctl get rc + +# kind: remote_cluster +# metadata: +# name: two +# status: +# connection: online +# last_heartbeat: "2020-09-14T03:13:59.35518164Z" +# version: v3 ``` Using `tctl` to update the labels on the remote/leaf cluster: -``` -$ tctl update rc/two --set-labels=env=prod +```bash +tctl update rc/two --set-labels=env=prod -cluster two has been updated +# Cluster two has been updated ``` Using `tctl` to confirm that the updated labels have been set: ```bash -$ tctl get rc -kind: remote_cluster -metadata: - labels: - env: prod - name: two - status: - connection: online - last_heartbeat: "2020-09-14T03:13:59.35518164Z" +tctl get rc + +# kind: remote_cluster +# metadata: +# labels: +# env: prod +# name: two +# status: +# connection: online +# last_heartbeat: "2020-09-14T03:13:59.35518164Z" ``` ## Using Trusted Clusters Now an admin from the "root" cluster can see and access the "leaf" cluster: -```bsh -# log into the root cluster: -$ tsh --proxy=root.example.com login admin +```bash +# Log into the root cluster: +tsh --proxy=root.example.com login admin ``` -```bsh -# see the list of available clusters -$ tsh clusters +```bash +# See the list of available clusters +tsh clusters +# Output Cluster Name Status ------------ ------ root online leaf online ``` -```bsh -# see the list of machines (nodes) behind the leaf cluster: -$ tsh ls --cluster=leaf +{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */} +```bash +# See the list of machines (nodes) behind the leaf cluster: +tsh ls --cluster=leaf + +# Output Node Name Node ID Address Labels --------- ------------------ -------------- ----------- db1.leaf cf7cc5cd-935e-46f1 10.0.5.2:3022 role=db-leader db2.leaf 3879d133-fe81-3212 10.0.5.3:3022 role=db-follower ``` -```bsh +{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */} + +```bash # SSH into any node in "leaf": -$ tsh ssh --cluster=leaf user@db1.leaf +tsh ssh --cluster=leaf user@db1.leaf ``` -### Disabling Trust +### Disabling trust To temporarily disable trust between clusters, i.e. to disconnect the "leaf" cluster from "root", edit the YAML definition of the trusted cluster resource and set `enabled` to "false", then update it: -```bsh -$ tctl create --force cluster.yaml +```bash +tctl create --force cluster.yaml ``` ### Remove Leaf Cluster relationship from both sides @@ -486,8 +470,7 @@ Remove the relationship from the leaf cluster: `tctl rm tc/root.example.com`. ## Sharing user traits between Trusted Clusters -You can share user SSH logins, Kubernetes users/groups and database users/names -between Trusted Clusters. +You can share user SSH logins, Kubernetes users/groups, and database users/names between Trusted Clusters. Suppose you have a root cluster with a role named `root` and the following allow rules: @@ -539,11 +522,9 @@ which is fairly easy to reason about: One can think of an SSH certificate as a "permit" issued and time-stamped by a certificate authority. A certificate contains four important pieces of data: -- List of allowed UNIX logins a user can use. They are called "principals" in - the certificate. +- List of allowed UNIX logins a user can use. They are called "principals" in the certificate. - Signature of the certificate authority who issued it (the *auth* server) -- Metadata (certificate extensions): additional data protected by the signature - above. Teleport uses the metadata to store the list of user roles and SSH +- Metadata (certificate extensions): additional data protected by the signature above. Teleport uses the metadata to store the list of user roles and SSH options like "permit-agent-forwarding". - The expiration date. @@ -555,7 +536,7 @@ certificate is presented to the auth server of "leaf" and it performs the following checks: - Checks that the certificate signature matches one of the trusted clusters. -- Tries to find a local role which maps to the list of principals found in the certificate. +- Tries to find a local role that maps to the list of principals found in the certificate. - Checks if the local role allows the requested identity (UNIX login) to have access. - Checks that the certificate has not expired. @@ -567,8 +548,7 @@ trust between two clusters: - **HTTPS configuration**: when the root cluster uses a self-signed or invalid HTTPS certificate. - **Connectivity problems**: when a leaf cluster "leaf" does not show up in `tsh clusters` output on "root". -- **Access problems**: when users from "root" get "access denied" error messages - trying to connect to nodes on "leaf". +- **Access problems**: when users from "root" get "access denied" error messages trying to connect to nodes on "leaf". ### HTTPS configuration @@ -577,7 +557,7 @@ you will get an error: "the trusted cluster uses misconfigured HTTP/TLS certific testing, the teleport daemon on "leaf" can be started with the `--insecure` CLI flag to accept self-signed certificates. Make sure to configure HTTPS properly and remove the insecure flag for production use. -### Connectivity Problems +### Connectivity problems To troubleshoot connectivity problems, enable verbose output for the auth servers on both clusters. Usually this can be done by adding `--debug` flag to @@ -585,17 +565,17 @@ servers on both clusters. Usually this can be done by adding `--debug` flag to file for both auth servers: ```yaml -# snippet from /etc/teleport.yaml +# Snippet from /etc/teleport.yaml teleport: log: output: stderr severity: DEBUG ``` -On systemd-based distributions you can watch the log output via: +On systemd-based distributions, you can watch the log output via: -```bsh -$ sudo journalctl -fu teleport +```bash +journalctl -fu teleport ``` Most of the time you will find out that either a join token is @@ -603,14 +583,12 @@ mismatched/expired, or the network addresses for `tunnel_addr` or `web_proxy_addr` cannot be reached due to pre-existing firewall rules or how your network security groups are configured on AWS. -### Access Problems +### Access problems Troubleshooting access denied messages can be challenging. A Teleport administrator should check to see the following: -- Which roles a user is assigned on "root" when they retrieve their SSH - certificate via `tsh login`. You can inspect the retrieved certificate with - `tsh status` command on the client side. +- Which roles a user is assigned on "root" when they retrieve their SSH certificate via `tsh login`. You can inspect the retrieved certificate with `tsh status` command on the client-side. - Which roles a user is assigned on "leaf" when the role mapping takes place. The role mapping result is reflected in the Teleport audit log. By default, it is stored in `/var/lib/teleport/log` on a *auth* server of a cluster.