[v6.2] Edit Pass #4 (#6974)

* docs: home section except for admin guide * docs: adminguide, ttl, oss * docs: corrected * docs: requested changes * docs: most of the reference section * docs: improve bash snippets * docs: bash corrections * docs: home section except for admin guide * docs: adminguide, ttl, oss * docs: corrected * docs: requested changes * docs: most of the reference section * docs: improve bash snippets * docs: bash corrections * docs: remove duplicate entries * docs: address faq issue * docs: initial access controls changes * docs: rest of access controls * docs: backport of 6809 * docs: bash corrections * docs: corrections * docs: requested changes tocless * docs: requested changes * docs: correct min tsh
gravitational · Jun 14, 2021 · 60f9e1c · 60f9e1c
1 parent b86a536
commit 60f9e1c
Show file tree

Hide file tree

Showing 21 changed files with 305 additions and 561 deletions.
diff --git a/docs/pages/access-controls/faq.mdx b/docs/pages/access-controls/faq.mdx
@@ -13,5 +13,4 @@ operator when evaluating node-level access using labels.
 
 **Q:** Can I use node-level RBAC with OpenSSH servers?
 
-**A:** No. OpenSSH servers running `sshd` do not have the ability to label
-themselves. This is one of the reasons to run Teleport `node` service instead.
+**A:** No. OpenSSH servers running `sshd` can't label themselves. This is a factor in deciding to run the Teleport Node service instead.
diff --git a/docs/pages/access-controls/getting-started.mdx b/docs/pages/access-controls/getting-started.mdx
@@ -1,12 +1,12 @@
 ---
 title: Getting Started With Access Controls
-description: Teleport Access Controls
+description: Get started using Teleport Access Controls.
 ---
 
 # Getting Started
 
-In Teleport, any local, SSO or robot user can be a member of one or several
-roles. Roles govern access to databases, SSH servers, kubernetes clusters and web apps.
+In Teleport, any local, SSO, or robot user can be a member of one or several
+roles. Roles govern access to databases, SSH servers, kubernetes clusters, and web apps.
 
 We will start with local users and preset roles, map SSO users to roles and wrap up
 with creating your own role.
@@ -19,16 +19,19 @@ with creating your own role.
 Verify that your Teleport client is connected:
 
 ```bash
-$ tctl status
+tctl status
+
+# Output
 Cluster  acme.example.com
 Version  6.0.2
 Host CA  never updated
 User CA  never updated
 Jwt CA   never updated
 CA pin   sha256:e63c7c44be468d37a5b0276b70e9d10b17f24f4be19d6b579810fc94eaa31783
 ```
+{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */}
 
-## Step 1/3 Add local users with preset roles
+## Step 1/3. Add local users with preset roles
 
 Teleport provides a [several preset roles](./reference.mdx#preset-roles): `admin`, `editor`, `auditor` and `access`.
 Members of the `editor` role can modify cluster configuration, members of `auditor`
@@ -38,33 +41,36 @@ Members of `admin`, are full cluster administrators.
 Invite a local user Alice as cluster `editor`:
 
 ```bash
-$ tctl users add alice --roles=editor
+tctl users add alice --roles=editor
 ```
 
 Once Alice signs up, she will be able to edit cluster configuration. You can list
 users and their roles using `tctl users ls`.
 
 ```bash
-$ tctl users ls
+tctl users ls
+
+# Output
 User                 Roles
 -------------------- -------------- 
 alice                editor
 [email protected]    admin
 ```
+{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */}
 
 You can update user's roles using `tctl users update` command:
 
 ```bash
-# Once Alice relogins, she will be able to view audit logs
-$ tctl users update alice --set-roles=editor,auditor
+# Once Alice logs back in, she will be able to view audit logs
+tctl users update alice --set-roles=editor,auditor
 ```
 
-Because Alice has two roles, permissions from those role create a union -
+Because Alice has two roles, permissions from those roles create a union -
 she will be able to act as a system administrator and auditor at the same time.
 
-## Step 2/3 Map SSO users to roles
+## Step 2/3. Map SSO users to roles
 
-We are going to setup Github connector for OSS and Okta for Enterprises version.
+We're now going to set up a GitHub connector for Teleport Open Source Edition and Okta for Teleport Enterprise Edition.
 
 <Tabs>
   <TabItem label="Open Source">
@@ -100,7 +106,7 @@ We are going to setup Github connector for OSS and Okta for Enterprises version.
     Follow [SAML Okta Guide](../enterprise/sso/ssh-okta.mdx#configure-okta) to create a SAML app.
     Check out [OIDC guides](../enterprise/sso/oidc.mdx#identity-providers) for OpenID Connect apps.
     Save the file below as `okta.yaml` and update the `acs` field.
-    Any member in Okta group `okta-admin` will assume a builtin role `admin`.
+    Any member in Okta group `okta-admin` will assume a built-in role `admin`.
 
     ```yaml
     kind: saml
@@ -118,7 +124,7 @@ We are going to setup Github connector for OSS and Okta for Enterprises version.
   </TabItem>
 </Tabs>
 
-## Step 3/3 Create a custom role
+## Step 3/3. Create a custom role
 
 Let's create a custom role for interns. Interns will have access
 to test or staging SSH servers as `readonly` users. We will let them
@@ -161,12 +167,12 @@ spec:
 Create a role using `tctl create -f` command:
 
 ```bash
-$ tctl create -f /tmp/interns.yaml
-# Get list of all roles in the system
-$ tctl get roles --format text
+tctl create -f /tmp/interns.yaml
+# Get a list of all roles in the system
+tctl get roles --format text
 ```
 
-## Next Steps
+## Next steps
 
 - [Mapping SSO and local users traits with role templates](./guides/role-templates.mdx)
 - [Create certs for CI/CD using impersonation](./guides/impersonation.mdx)
diff --git a/docs/pages/access-controls/guides.mdx b/docs/pages/access-controls/guides.mdx
@@ -1,12 +1,23 @@
 ---
 title: Access Controls Guides
 description: Detailed guides for configuring Teleport Access Controls
+layout: tocless-doc
 ---
 
-# Guides
-
-- [Dynamic access policies with role templates](./guides/role-templates.mdx)
-- [Create certs for CI/CD using impersonation](./guides/impersonation.mdx)
-- [Second Factor - U2F](./guides/u2f.mdx)
-- [Per-session MFA](./guides/per-session-mfa.mdx)
-- [Dual Authorization with ChatOps](./guides/dual-authz.mdx)
+<TileSet>
+  <Tile icon="lock" title="Dual Authorization" href="./guides/dual-authz.mdx">
+      Dual Authorization for SSH and Kubernetes.
+  </Tile>
+  <Tile icon="lock" title="Teleport Role Templates" href="./guides/role-templates.mdx">
+     Dynamic Access Policies with Role Templates.
+  </Tile>
+  <Tile icon="lock" title="Impersonating Teleport Users" href="./guides/impersonation.mdx">
+    Create certs for CI/CD using impersonation.
+  </Tile>
+  <Tile icon="lock" title="Second Factor - U2F" href="./guides/u2f.mdx">
+    Add Two-Factor Authentication through U2F.
+  </Tile>
+  <Tile icon="lock" title="Per-session MFA" href="./guides/per-session-mfa.mdx">
+    Per-session Multi-Factor Authentication.
+  </Tile>
+</TileSet>
diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx
@@ -23,6 +23,10 @@ two team members for a privileged role `dbadmin`.
   an SSO provider.
 </Admonition>
 
+<Admonition title="Note" type="tip">
+  The steps below describe how to use Teleport with Mattermost. You can also [integrate with many other providers](../../enterprise/workflow/index.mdx).
+</Admonition>
+
 ## Prerequisites
 
 - Installed [Teleport Enterprise](../../enterprise/introduction.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=)
@@ -41,36 +45,39 @@ two team members for a privileged role `dbadmin`.
 Verify that your Teleport client is connected:
 
 ```bash
-$ tctl status
+tctl status
+
+# Output
 Cluster  acme.example.com
 Version  6.0.2
 Host CA  never updated
 User CA  never updated
 Jwt CA   never updated
 CA pin   sha256:e63c7c44be468d37a5b0276b70e9d10b17f24f4be19d6b579810fc94eaa31783
 ```
+{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */}
 
-## Setup Teleport Bot
+## Set up Teleport bot
 
 <Tabs>
-<TabItem label="Mattermost">
+  <TabItem label="Mattermost">
 
-Enable bot account creation in `System Console -> Integrations`.
-Toggle `Enable Bot Account Creation`.
+  Enable bot account creation in "System Console -> Integrations".
+  Toggle `Enable Bot Account Creation`.
 
-![Enable bots](../../../img/access-controls/dual-authz/mattermost-0-enable.png)
+  ![Enable bots](../../../img/access-controls/dual-authz/mattermost-0-enable.png)
 
-Go back to your team settings, navigate to `Integrations -> Bot Accounts`. Press `Add Bot Account`.
+  Go back to your team settings, navigate to "Integrations -> Bot Accounts". Press "Add Bot Account".
 
-![Enable bots](../../../img/access-controls/dual-authz/mattermost-1-bot.png)
+  ![Enable bots](../../../img/access-controls/dual-authz/mattermost-1-bot.png)
 
-Add `Post All` permission on the new account.
+  Add the "Post All" permission on the new account.
 
-![Enable bots](../../../img/access-controls/dual-authz/[email protected])
+  ![Enable bots](../../../img/access-controls/dual-authz/[email protected])
 
-Create the bot and save the access token.
+  Create the bot and save the access token.
 
-</TabItem>
+  </TabItem>
 </Tabs>
 
 Create a non-interactive bot `access-plugin` user and role.
@@ -104,8 +111,9 @@ spec:
   title="Creating resources"
 >
   Here and below follow along and create yaml resources using `tctl create -f`:
+
   ```bash
-  $ tctl create -f access.yaml
+  tctl create -f access.yaml
   ```
 </Admonition>
 
@@ -116,7 +124,7 @@ Teleport Plugin uses the `access-plugin` role and user to perform the approval.
 We export the identify files, using `tctl auth sign`.
 
 ```bash
-$ tctl auth sign --format=tls --user=access-plugin --out=auth --ttl=720h
+tctl auth sign --format=tls --user=access-plugin --out=auth --ttl=720h
 ```
 
 Teleport will generate `auth.crt`, `auth.key`, and `auth.cas` - a certificate, a private key, and a set of CA certs respectively.
@@ -126,51 +134,36 @@ Teleport will generate `auth.crt`, `auth.key`, and `auth.cas` - a certificate, a
 <Tabs>
 <TabItem label="Download">
   ```bash
-  $ curl -L https://get.gravitational.com/teleport-access-mattermost-v(=teleport.version=)-linux-amd64-bin.tar.gz
-  $ tar -xzf teleport-access-mattermost-v(=teleport.version=)-linux-amd64-bin.tar.gz
-  $ cd teleport-access-mattermost
-  $ ./install
+  curl -L https://get.gravitational.com/teleport-access-mattermost-v(=teleport.version=)-linux-amd64-bin.tar.gz
+  tar -xzf teleport-access-mattermost-v(=teleport.version=)-linux-amd64-bin.tar.gz
+  cd teleport-access-mattermost
+  ./install
   ```
 </TabItem>
 <TabItem label="From Source">
   To install from source you need `git` and `go >= (=teleport.golang=)` installed.
 
   ```bash
   # Checkout teleport-plugins
-  $ git clone https://github.com/gravitational/teleport-plugins.git
-  $ cd teleport-plugins/access/mattermost
-  $ make
+  git clone https://github.com/gravitational/teleport-plugins.git
+  cd teleport-plugins/access/mattermost
+  make
   ```
 </TabItem>
 </Tabs>
 
 
 ```bash
-$ teleport-mattermost configure > /etc/teleport-mattermost.toml
+sudo teleport-mattermost configure > /etc/teleport-mattermost.toml
 ```
 
 Update the config with Teleport address, Mattermost URL, and a bot token.
 
 ```toml
-# example Mattermost configuration TOML file
-[teleport]
-# For Teleport Cloud you can point to the proxy: "example.teleport.sh:443"
-auth_server = "teleport.example.com:3025"  # Teleport Auth Server GRPC API address
-client_key = "/var/lib/teleport/plugins/mattermost/auth.key" # Teleport GRPC client secret key
-client_crt = "/var/lib/teleport/plugins/mattermost/auth.crt" # Teleport GRPC client certificate
-root_cas = "/var/lib/teleport/plugins/mattermost/auth.cas"   # Teleport cluster CA certs
-
-[mattermost]
-url = "https://mattermost.example.com" # Mattermost Server URL
-token = "api-token"                    # Mattermost Bot OAuth token
-recipients = [team/channel]            # Mattermost Team or Channel to notify of new requests
-
-[log]
-output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/mattermost.log"
-severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".
+(!examples/resources/plugins/teleport-mattermost.toml!)
 ```
 
-## Dual Authorization
+## Dual authorization
 
 Alice and Ivan are reviewers - they can approve requests for assuming role `dbadmin`.
 Bob is a devops and can assume `dbadmin` role if two members of the `reviewer` role
@@ -216,12 +209,12 @@ Example below creates local users Alice, Ivan and Bob.
 Bob does not have a role `dbadmin` assigned to him, but can create an access request for it.
 
 ```bash
-$ tctl users add [email protected] --roles=devops
-$ tctl users add [email protected] --roles=reviewer
-$ tctl users add [email protected] --roles=reviewer
+tctl users add [email protected] --roles=devops
+tctl users add [email protected] --roles=reviewer
+tctl users add [email protected] --roles=reviewer
 ```
 
-## Access Requests Flow
+## Access Requests flow
 
 Bob can create an access request for the `dbadmin` role in the Web UI or CLI:
 
@@ -249,17 +242,21 @@ Alice and Ivan can review and approve request using Web UI or CLI:
 </TabItem>
 <TabItem label="CLI">
   ```bash
-  $ tsh request list
+  tsh request list
+  
+  # Output
   ID                                   User             Roles   Created (UTC)       Status
   ------------------------------------ ---------------  ------- ------------------- ------- 
   9c721e54-b049-4ef8-a7f6-c777aa066764 [email protected]  dbadmin 03 Apr 21 03:58 UTC PENDING
 
-  $tsh request review --approve --reason="hello" 9c721e54-b049-4ef8-a7f6-c777aa066764
-  Successfully submitted review.  Request state: APPROVED
+  tsh request review --approve --reason="hello" 9c721e54-b049-4ef8-a7f6-c777aa066764
+  # Successfully submitted review.  Request state: APPROVED
   ```
 </TabItem>
 </Tabs>
 
+{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */}
+
 If Bob has created a request using CLI, he will assume it once it has been approved.
 Bob can also assume granted access request roles using Web UI: