opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-10-25 00:19:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

Grammar improvements to Teleport Doc (#3388)

Browse Source 
Co-authored-by: Ben Arent <ben@gravitational.com>
This commit is contained in:
Claire Muller
2020-03-02 13:40:53 -08:00
committed by GitHub
co-authored by Ben Arent
parent 748691ff19
commit da91482ae0
7 changed files with 41 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/4.2.yaml
+2 -2
View File
@@ -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
docs/4.2/admin-guide.md
+3 -3
View File
@@ -663,7 +663,7 @@ tsh --proxy <proxy-addr> ssh <hostname>
## 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
docs/4.2/architecture/teleport_auth.md
+23 -29
View File
@@ -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. <!--TODO: Why?-->
### 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" <!--TODO: link to config/set options
here-->.
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.
@@ -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_ <!--TODO: Link to
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.
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
docs/4.2/architecture/teleport_nodes.md
+2 -2
View File
@@ -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).
docs/4.2/enterprise/index.md
+8 -8
View File
@@ -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.
docs/4.2/enterprise/quickstart-enterprise.md
+2 -2
View File
@@ -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
docs/4.2/quickstart.md
+1 -1
View File
@@ -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: