From da91482ae0afe437bef22d196bd8d8d1af06dbb3 Mon Sep 17 00:00:00 2001 From: Claire Muller Date: Mon, 2 Mar 2020 13:40:53 -0800 Subject: [PATCH] Grammar improvements to Teleport Doc (#3388) Co-authored-by: Ben Arent --- docs/4.2.yaml | 4 +- docs/4.2/admin-guide.md | 6 +-- docs/4.2/architecture/teleport_auth.md | 52 +++++++++----------- docs/4.2/architecture/teleport_nodes.md | 4 +- docs/4.2/enterprise/index.md | 16 +++--- docs/4.2/enterprise/quickstart-enterprise.md | 4 +- docs/4.2/quickstart.md | 2 +- 7 files changed, 41 insertions(+), 47 deletions(-) diff --git a/docs/4.2.yaml b/docs/4.2.yaml index 33c746f3d38..855c8d72667 100644 --- a/docs/4.2.yaml +++ b/docs/4.2.yaml @@ -32,9 +32,9 @@ extra_javascript: [] extra: version: 4.2 teleport: - version: 4.2.2 + version: 4.2.3 golang: 1.13 - sha: ab3828386563c956adc16dc5d746bbb8dd70ac4d82767549bb80a73568a8fb39 + sha: 1c14362c9ba10f28088c7228b357dc6a70072d3d4afaa5510c70a8734068684c nav: - Documentation: - Introduction: index.md diff --git a/docs/4.2/admin-guide.md b/docs/4.2/admin-guide.md index 1ee0e15f85c..472a54d7256 100644 --- a/docs/4.2/admin-guide.md +++ b/docs/4.2/admin-guide.md @@ -663,7 +663,7 @@ tsh --proxy ssh ## Adding and Deleting Users -This section covers internal user identities, i.e.user accounts created and +This section covers internal user identities, i.e. user accounts created and stored in Teleport's internal storage. Most production users of Teleport use _external_ users via [Github](#github-oauth-20) or [Okta](ssh_okta) or any other SSO provider (Teleport Enterprise supports any SAML or OIDC compliant identity @@ -1057,7 +1057,7 @@ the audit log: 3. **Optional: Enhanced Session Recording** Refer to the ["Audit Log" chapter in the Teleport -Architecture](architecture/teleport_auth.md#audit-log) to learn more about how the audit Log and +Architecture](architecture/teleport_auth.md#audit-log) to learn more about how the audit log and session recording are designed. ### SSH Events @@ -1066,7 +1066,7 @@ Teleport supports multiple storage back-ends for storing the SSH events. The section below uses the `dir` backend as an example. `dir` backend uses the local filesystem of an auth server using the configurable `data_dir` directory. -For highly available (HA) configuration users can refer to +For highly available (HA) configuration, users can refer to our [DynamoDB](#using-dynamodb) or [etcd](#using-etcd) chapters on how to configure the SSH events and recorded sessions to be stored on network storage. It is even possible to store the audit log in multiple places at the same time, see diff --git a/docs/4.2/architecture/teleport_auth.md b/docs/4.2/architecture/teleport_auth.md index 08161dc9948..58405b44b0e 100644 --- a/docs/4.2/architecture/teleport_auth.md +++ b/docs/4.2/architecture/teleport_auth.md @@ -11,23 +11,23 @@ Nodes and Services. ## Authentication vs. Authorization Teleport Auth handles both authentication and authorization. These topics are -related but different and they are often discussed jointly as "Auth". +related but different, and they are often discussed jointly as "Auth". **Authentication** is proving an identity. "I say I am Bob, and I really am Bob. -See look I have Bob's purple hat.". The job of an Authentication system is to +See look I have Bob's purple hat." The job of an Authentication system is to define the criteria by which users must prove their identity. Is having a purple hat enough to show that a person is Bob? Maybe, maybe not. To identify users and -nodes to Teleport Auth we require them to present a cryptographically-signed +nodes to Teleport Auth, we require them to present a cryptographically-signed 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 +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 +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 +banking system, or data in a filesystem. Before users are granted access to nodes, the Auth Service checks their identity against a stored mapping in a database. @@ -60,7 +60,7 @@ need their own certificates. ### Issuing Node Certificates Node Certificates identify a node within a cluster and establish the permissions -of the node to access to other Teleport services. The presence of a signed +of the node to access other Teleport services. The presence of a signed certificate on a node makes it a cluster member. ![Node Joins Cluster](../img/node_join.svg) @@ -70,7 +70,7 @@ certificate on a node makes it a cluster member. dynamic, single-use token generated by [`tctl nodes add`](../cli-docs.md#tctl-nodes-add). - !!! tip "Token TTL": + !!! tip "Token TTL" When using dynamic tokens, their default time to live (TTL) is 15 minutes, but it can be reduced (not increased) via [`tctl nodes add --ttl`](../cli-docs.md#tctl-nodes-add) flag. @@ -102,19 +102,17 @@ 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.md#tsh-login) or via the Web UI. The Auth Server check - these against its identity storage and checks the 2nd factor token. + login`](../cli-docs.md#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 + signed certificate and return it to the client. For users, certificates are stored in `~/.tsh` by default. If the client uses the [Web UI](./proxy/#web-ui-to-ssh) the signed certificate is associated with a secure websocket session. -In addition to user's identity, user certificates also contain user roles and -SSH options, like "permit-agent-forwarding" . - +In addition to a user's identity, user certificates also contain user roles and +SSH options, like "permit-agent-forwarding" . This additional data is stored as a certificate extension and is protected by the CA signature. @@ -122,38 +120,36 @@ the CA signature. ![Client offers valid certificate](../img/user_auth.svg) -When a client requests to access a node cluster, the Auth Server first checks +When a client requests access to a node cluster, the Auth Server first checks that a certificate exists and hasn't expired. If it has expired, the client must re-authenticate with their username, password, and 2nd factor. If the certificate is still valid, the Auth Server validates the certificate's -signature. - -If it is correct the client is granted access to the cluster. From here, the +signature. The client is then granted access to the cluster. From here, the [Proxy Server](teleport_proxy.md#connecting-to-a-node) establishes a connection between client and node. ## 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. But the node +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. Certificate rotation is triggered by [`tctl auth rotate`](../cli-docs.md#tctl-auth). When this command is invoked by a Teleport -administrator on one of cluster's Auth Servers, the following happens: +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_ 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, one for the node CA and once for the user CA. +This process is repeated twice, once for the node CA and once for the user CA. Take a look at the [Certificate Guide](../admin-guide.md#certificate-rotation) to learn how to do certificate rotation in practice. @@ -193,16 +189,15 @@ There are three types of data stored by the auth server: ## Audit Log The Teleport auth server keeps the audit log of SSH-related events that take -place on any node with a Teleport cluster. Each node in a cluster emits audit -events and submit them to the auth server. The events recorded include: +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 -!!! warning "Compatibility Warning": - +!!! warning "Compatibility Warning" Because all SSH events like `exec` or `session_start` are reported by the Teleport node service, they will not be logged if you are using OpenSSH @@ -216,8 +211,7 @@ in the [Admin Manual](../admin-guide.md#audit-log). Teleport users are encouraged to export the events into external, long term storage. -!!! info "Deployment Considerations": - +!!! info "Deployment Considerations" If multiple Teleport auth servers are used to service the same cluster (HA mode) a network file system must be used for diff --git a/docs/4.2/architecture/teleport_nodes.md b/docs/4.2/architecture/teleport_nodes.md index 7c8b6dcdc5e..a2797243ded 100644 --- a/docs/4.2/architecture/teleport_nodes.md +++ b/docs/4.2/architecture/teleport_nodes.md @@ -6,7 +6,7 @@ ## The Node Service -A regular node becomes a Teleport Node when the node joins a cluster with an +A regular 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](teleport_auth.md#issuing-node-certificates). @@ -19,7 +19,7 @@ and remote command execution on the node, similar to the function of OpenSSH's ![Node Service ping API](../img/node_service_api.svg) -All cluster Nodes keep the Auth Server updated with their status with periodic +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](teleport_auth.md#auth-api). diff --git a/docs/4.2/enterprise/index.md b/docs/4.2/enterprise/index.md index f3ac5367098..b69046fd3af 100644 --- a/docs/4.2/enterprise/index.md +++ b/docs/4.2/enterprise/index.md @@ -20,9 +20,9 @@ The table below gives a quick overview of the benefits of Teleport Enterprise. ## RBAC -Role Based Access Control ("RBAC") allows Teleport administrators to grant granular access permissions to user's. An example of an RBAC policy might be: _"admins can do anything, +Role Based Access Control ("RBAC") allows Teleport administrators to grant granular access permissions to users. An example of an RBAC policy might be: _"admins can do anything, developers must never touch production servers, and interns can only SSH into -staging servers as guests"_ +staging servers as guests". ### How does it work? @@ -31,7 +31,7 @@ edition of Teleport automatically assigns every user to the built-in "admin" role, but Teleport Enterprise allows administrators to define their own roles with far greater control over user permissions. -Lets assume a company is using Active Directory to authenticate users and place +Let's assume a company is using Active Directory to authenticate users and place them into groups. A typical enterprise deployment of Teleport in this scenario would look like this: @@ -41,7 +41,7 @@ would look like this: "developers", "admins", "contractors", etc. 3. The Teleport administrator will have to define Teleport Roles. For example: "users", "developers" and "admins". -4. The last step will be to define mappings from the Active Directory groups (claims). +4. The last step will be to define mappings from the Active Directory groups (claims) to the Teleport Roles so every Teleport user will be assigned a role based on the group membership. @@ -74,7 +74,7 @@ $ tsh login Teleport can be configured with a certificate TTL to determine how often a user needs to log in. `tsh login` will print a URL into the console, which will open an SSO login -prompt, along with the 2FA, as enforced by the SSO provider. If user supplies +prompt, along with the 2FA, as enforced by the SSO provider. If a user supplies valid credentials, Teleport will issue an SSH certificate. Moreover, SSO can be used in combination with role-based access control (RBAC) @@ -84,7 +84,7 @@ See the [SSO for SSH](ssh_sso.md) chapter for more details. !!! tip "Contact Information" - For more information about Teleport Enterprise or Gravity please reach out us to `sales@gravitational.com` or fill out the contact for on our [website](http://gravitational.com/demo) + For more information about Teleport Enterprise or Gravity please reach out us to `sales@gravitational.com` or fill out the contact form on our [website](http://gravitational.com/demo). ## FedRAMP/FIPS @@ -153,7 +153,7 @@ spec: ``` **Admin Role** -This role lets the admin approve the contractors request. +This role lets the admin approve the contractor's request. ```yaml kind: role metadata: @@ -205,6 +205,6 @@ Assuming approval, `tsh` will automatically manage a certificate re-issued with ### Other features of Approval Workflows. - - Roles can request multiple roles at one time. e.g `roles: ['dba','netsec','cluster-x']` + - Users can request multiple roles at one time. e.g `roles: ['dba','netsec','cluster-x']` - Approved requests have no affect on Teleport's behavior outside of allowing additional roles on re-issue. This has the nice effect of making requests "compatible" with older versions of Teleport, since only the issuing Auth Server needs any particular knowledge of the feature. \ No newline at end of file diff --git a/docs/4.2/enterprise/quickstart-enterprise.md b/docs/4.2/enterprise/quickstart-enterprise.md index d4d97f21a54..a322d08a934 100644 --- a/docs/4.2/enterprise/quickstart-enterprise.md +++ b/docs/4.2/enterprise/quickstart-enterprise.md @@ -30,7 +30,7 @@ interact with it using Teleport's client-side tools: You will need to have access to the [customer portal](https://dashboard.gravitational.com) to download the software. You will also need three computers: two servers and -one client (probably a laptop) to complete this tutorial. Lets assume the servers have +one client (probably a laptop) to complete this tutorial. Let's assume the servers have the following DNS names and IPs: Server Name | IP Address | Purpose @@ -38,7 +38,7 @@ Server Name | IP Address | Purpose _"auth.example.com"_ | 10.1.1.10 | This server will be used to run all three Teleport services: auth, proxy and node. _"node.example.com"_ | 10.1.1.11 | This server will only run the SSH service. The vast majority of servers in production will be nodes. -This Quick Start Guide assumes that the both servers are running a [systemd-based](https://www.freedesktop.org/wiki/Software/systemd/) +This Quick Start Guide assumes that both servers are running a [systemd-based](https://www.freedesktop.org/wiki/Software/systemd/) Linux distribution such as Debian, Ubuntu or a RHEL derivative. ## Installing diff --git a/docs/4.2/quickstart.md b/docs/4.2/quickstart.md index 253a3e16071..ce8e27ed05c 100644 --- a/docs/4.2/quickstart.md +++ b/docs/4.2/quickstart.md @@ -214,7 +214,7 @@ howdy _Note: The `tsh` client always requires the `--proxy` flag_ -You command prompt may not look different, but you are now in a new SSH session +Your command prompt may not look different, but you are now in a new SSH session which has been authenticated by Teleport! Try a few things to get familiar with recorded sessions: