Edit four Access Controls guides for Cloud users

Backports #11838 * Edit four Access Controls guides for Cloud users See #10638 Per-session MFA - Add scoped Tabs to the Prerequisites section - Add a ScopedBlock so Cloud users don't see the option to enable per-session MFA via static config - Minor copy-edits and organization edits. For example, turn a section that refers to an example in another section into an Admonition. Dual Authorization - Add scoped Tabs to the Prerequisites - Use a scoped Notice for the edition warning - Style/clarity/grammar edits - Hide the Troubleshooting section for Cloud users Moderated Sessions - Change the edition warning to a scoped Notice. Since this guide is a conceptual guide rather than a step-by-step tutorial, there's no other scope-irrelevant information to hide. Impersonation - Add scoped Tabs to the Prerequisites - Used ScopedBlocks to hide minor scope-irrelevant details - Minor style/grammar/clarity edits * Respond to PR feedback * Respond to PR feedback
gravitational · Apr 15, 2022 · 43ef908 · 43ef908
1 parent a6e4489
commit 43ef908
Show file tree

Hide file tree

Showing 4 changed files with 176 additions and 61 deletions.
diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx
@@ -7,14 +7,15 @@ videoBanner: b_iqJm_o15I
 You can set up Teleport to require require the approval of multiple team members to perform some critical actions.
 Here are the most common scenarios:
 
-- Improve security of your system and prevent one successful phishing attack from compromizing your system.
+- Improve the security of your system and prevent one successful phishing attack from compromising your system.
 - Satisfy FedRAMP AC-3 Dual authorization control that requires approval of two authorized individuals.
 
-Let's set up Teleport's access requests to require approval of
-two team members for a privileged role `dbadmin`.
+Let's set up Teleport's access requests to require the approval of two team members
+for a privileged role `dbadmin`.
 
 <Notice
-  type="warning"
+  type="danger"
+  scope="oss"
 >
   This guide requires a commercial edition of Teleport. The open source
   edition of Teleport only supports [GitHub](../../setup/admin/github-sso.mdx) as
@@ -32,7 +33,7 @@ two team members for a privileged role `dbadmin`.
   scope={["enterprise"]} label="Enterprise">
 
 - A running Teleport cluster. For details on how to set this up, see our Enterprise
-  [Getting Started](/docs/enterprise/getting-started) guide.
+  [Getting Started](../../enterprise/getting-started.mdx) guide.
 
 - The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=),
   which you can download by visiting the
@@ -53,15 +54,15 @@ two team members for a privileged role `dbadmin`.
 - A Teleport Cloud account. If you do not have one, visit the
   [sign up page](https://goteleport.com/signup/) to begin your free trial.
 
-- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=).
-  To download these tools, visit the [Downloads](/docs/cloud/downloads) page.
+- The `tctl` admin tool and `tsh` client tool.
+  To download these tools, visit the [Downloads](https://goteleport.com/download/) page.
 
   ```code
   $ tctl version
-  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  # Teleport v(=cloud.version=) go(=teleport.golang=)
   
   $ tsh version
-  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  # Teleport v(=cloud.version=) go(=teleport.golang=)
   ```
 
 </TabItem>
@@ -80,7 +81,7 @@ two team members for a privileged role `dbadmin`.
 
 (!docs/pages/includes/tctl.mdx!)
 
-## Set up Teleport bot
+## Step 1/3. Set up a Teleport bot
 
 ### Create a bot within Mattermost
 
@@ -146,20 +147,25 @@ Update the config with the Teleport address, Mattermost URL, and a bot token.
 (!examples/resources/plugins/teleport-mattermost-self.toml!)
 ```
 </TabItem>
-<TabItem scope={["cloud"]} label="Cloud">
+<TabItem scope={["cloud"]} label="Teleport Cloud">
 ```yaml
 (!examples/resources/plugins/teleport-mattermost-cloud.toml!)
 ```
 </TabItem>
 </Tabs>
 
-## Dual authorization
+## Step 2/3. Configure dual authorization
+
+In this section, we will use an example to show you how to require dual
+authorization for a user to assume a role.
 
-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
-approved the request.
+### Require dual authorization for a role
 
-Create `dbadmin`, `reviewer` and `devops` roles:
+Alice and Ivan are reviewers. They can approve requests for assuming role
+`dbadmin`. Bob is a DevOps engineer and can assume the `dbadmin` role if two members
+of the `reviewer` role approve the request.
+
+Create the following `dbadmin`, `reviewer` and `devops` roles:
 
 ```yaml
 kind: role
@@ -195,17 +201,17 @@ spec:
       'type': 'db'
 ```
 
-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.
+The commands below create the local users Bob, Alice, and Ivan.
 
 ```code
 $ tctl users add bob@example.com --roles=devops
 $ tctl users add alice@example.com --roles=reviewer
 $ tctl users add ivan@example.com --roles=reviewer
 ```
 
-## Access Requests flow
+### Create an access request
+
+Bob does not have a role `dbadmin` assigned to him, but can create an access request for it.
 
 Bob can create an access request for the `dbadmin` role in the Web UI or CLI:
 
@@ -251,11 +257,16 @@ Bob can also assume granted access request roles using Web UI:
 
 ![Teleport Assume](../../../img/access-controls/dual-authz/teleport-7-bob-assume.png)
 
+
+{/* TODO: This H2 will show up in the table of contents when this section is invisible.
+We need a way to hide invisible H2s from the TOC. */}
+<ScopedBlock scope={["oss", "enterprise"]}>
+
 ## Troubleshooting
 
 ### Cert errors in self-hosted deployments
 
-You may be getting certificate errors if Teleport's auth server is missing an address in the server certificate:
+You may be getting certificate errors if Teleport's Auth Service is missing an address in the server certificate:
 
 ```txt
 authentication handshake failed: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs
@@ -265,9 +276,11 @@ authentication handshake failed: x509: cannot validate certificate for 127.0.0.1
 x509: certificate is valid for,*.teleport.cluster.local, teleport.cluster.local, not example.com
 ```
 
-To fix the problem, update the auth service with a public address, and restart Teleport:
+To fix the problem, update the Auth Service with a public address, and restart Teleport:
 
 ```yaml
 auth_service:
   public_addr: ['localhost:3025', 'example.com:3025']
 ```
+
+</ScopedBlock>
diff --git a/docs/pages/access-controls/guides/impersonation.mdx b/docs/pages/access-controls/guides/impersonation.mdx
@@ -3,8 +3,6 @@ title: Impersonating Teleport Users
 description: How to issue short-lived certs on behalf of Teleport users using impersonation.
 ---
 
-# Impersonation
-
 Sometimes users need to create short-lived certificates for non-interactive
 users, for example, CI/CD systems. Your programs interacting with Teleport may
 need to create their own authentication as well. Teleport's impersonation allows
@@ -21,13 +19,13 @@ non-interactive CI/CD user Jenkins and a security scanner.
 
 ## Step 1/3: Create a CI/CD user and corresponding role
 
-First, let's create a role called `jenkins`. Notice the `max_session_ttl`
+First, we will create a role called `jenkins`. Notice the `max_session_ttl`
 parameter, which limits the cert duration for certificates issued to users with
 this role. As a rule of thumb, the shorter the TTL, the better.
 
-Next, we'll create a user also named `jenkins` and assign the role to the user.
+We will also create a user also named `jenkins` and assign the role to the user.
 
-Save this file as `jenkins.yaml` to create the user and role:
+Save this file as `jenkins.yaml`:
 
 ```yaml
 kind: role
@@ -56,20 +54,15 @@ spec:
   roles: ['jenkins']
 ```
 
-<Admonition
-  type="note"
-  title="Audit"
->
-  Here and below follow along and create yaml resources using `tctl create -f`:
+Create the resources:
 
-  ```code
-  $ tctl create -f jenkins.yaml
-  ```
-</Admonition>
+```code
+$ tctl create -f jenkins.yaml
+```
 
 ## Step 2/3: Create an impersonator role
 
-Let's create a role `impersonator`. Users with this role will be permitted to
+Next, we will create a role called `impersonator`. Users with this role will be permitted to
 impersonate the `jenkins` user and role.
 
 Save this role definition as `impersonator.yaml`:
@@ -100,7 +93,13 @@ spec:
       '*': '*'
 ```
 
-Next, create an interactive user `alice` and assign the impersonator role so
+Create the `role` resource:
+
+```code
+$ tctl create -f impersonator.yaml
+```
+
+Next, create an interactive user named `alice` and assign the impersonator role so
 that `alice` can impersonate `jenkins`. 
 
 <Admonition
@@ -117,13 +116,25 @@ $ tctl users add alice  --roles=impersonator,access
 
 ## Step 3/3: Use impersonation to issue a certificate
 
-Alice can login using `tsh` and issue a cert for `jenkins`:
+Alice can log in using `tsh` and issue a cert for `jenkins`:
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+
+```code
+$ tsh login --proxy=proxy.example.com --user=alice --auth=local
+$ tctl auth sign --user=jenkins --format=openssh --out=jenkins --ttl=240h
+```
+
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
 
 ```code
-$ tsh login --proxy=teleport.localhost --user=alice --auth=local
+$ tsh login --proxy=mytenant.teleport.sh --user=alice --auth=local
 $ tctl auth sign --user=jenkins --format=openssh --out=jenkins --ttl=240h
 ```
 
+</ScopedBlock>
+
 Here is an example of how Alice can use the keys:
 
 ```code
@@ -160,10 +171,10 @@ To prevent unintended consequences, Teleport defines the following impersonation
   being impersonated.
 - Even if the `jenkins` role could impersonate some other roles, Alice would not
   be able to use this permission. Teleport prevents recursive impersonation.
-- Alice can get a new `jenkins` certificate with the same TTL, but metadata
-  updated, for example pointing to a different Teleport leaf cluster. Teleport
-  allows impersonated users to renew their certificates with the reduced scope
-  of the certificate.
+- Alice can get a new `jenkins` certificate with the same TTL, but with the
+  metadata updated, for example, to point to a different Teleport leaf cluster.
+  Teleport allows impersonated users to renew their certificates with the
+  reduced scope of the certificate.
 
 ### Dynamic Impersonation
 
@@ -174,7 +185,7 @@ based on matching labels.
 
 For example, suppose you wanted to define a `security-impersonator` role that
 allowed the impersonation of any users or roles with the label
-`group: security`. This could be accomplished with the folowing role definition:
+`group: security`. This could be accomplished with the following role definition:
 
 ```yaml
 kind: role
@@ -245,11 +256,11 @@ the `group: security` label.
 $ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h
 ```
 
-**Matching user traits**
+### Matching user traits
 
 We can also define impersonation rules by matching against user traits.
 
-Here we update the `security-impersonator` role to allow for the impersonation
+Here we updated the `security-impersonator` role to allow for the impersonation
 of any other users or roles where the `group` user trait contains the same value
 as the label on the role and/or user to impersonate:
 
@@ -278,7 +289,7 @@ spec:
 ```
 
 While user traits typically come from an external identity provider, we can test
-with local user `alice` by manually updating Alices's account with traits.
+with local user `alice` by manually updating Alice's account with traits.
 
 ```yaml
 kind: user
@@ -297,12 +308,9 @@ Since Alice's `group` trait contains `security`, and the `security-scanner` user
 has a label of `group: security`, Alice will be able to impersonate the security
 scanner.
 
-<Admonition
-  type="note"
-  title="Login"
->
-Alice will need to log in again to receive the newly updated traits.
-</Admonition>
+Alice will need to log in again to receive the newly updated traits:
+
+<ScopedBlock scope={["oss", "enterprise"]}>
 
 ```code
 # Once Alice logs in again, she will receive a new certificate with updated roles.
@@ -311,6 +319,20 @@ $ tsh login --proxy=teleport.example.com --user=alice --auth=local
 $ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h
 ```
 
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```code
+# Once Alice logs in again, she will receive a new certificate with updated roles.
+$ tsh login --proxy=mytenant.teleport.sh --user=alice --auth=local
+# Alice can now get a certificate for the security scanner
+$ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h
+```
+
+</ScopedBlock>
+
+### Filter fields
+
 Here is a summary of variables and functions we used in this guide:
 
 <table>