Edit two guides for Cloud users

Backports #11419 * Edit two guides for Cloud users PAM guide - Minor style/clarity/grammar edits - Use a ScopedBlock to hide Cloud-irrelevant information in the MOTD section - The organization of the original guide was a bit scrambled, so I attempted to reorganize it into a form that made more sense. Tsh guide - Use ScopedBlocks to provide scope-relevant information. - Mention Machine ID in the "### SSH certificates for automation" section. - Misc grammar/clarity/style edits * Respond to PR feedback Clarify two guides and two intro pages Backports #11913 * Clarify two guides and two intro pages See #11841 Make the Adding Nodes guide more usable for Cloud - Add a ca_pin preset - Clarify that tctl must be run on the local machine for Cloud users - Structure the guide as a step-by-step tutorial. The guide already included sequences of sample commands, so all this took was to rename headings according to the "Step n/d." format and move the CA pinning section into the section on starting the Node. - Add environment variables to use for storing a CA pin and invite token to sample commands, plus piped commands to extract these strings from the output of tctl commands. - Use a ScopedBlock to hide the Node Tunneling section for Cloud users - Indicate that the --auth-server flag in "teleport start" requires a port. Add intros to the Admin and Operations menu pages - Clarify the purpose of the Admin Guides and Operations sections by adding an intro paragraph to each page. Since these sections are similar in scope, I added links from one to the other with statements about how the two sections differ. - Replace lists of links with Tiles. GitHub SSO - Move the step to create an OAuth app out of the Prerequisites and into its own step. This makes it easier to give the instructions to use a specific callback URL proper space. - Be more explicit about the rp_ip value. - Add explicit instructions for logging in to the cluster after creating the auth preference, including screenshots of expected results. * Fix wording and linter issues following PR review * Respond to PR feedback Remove a misleading instruction re: CA pinning. Also move some text about CA pinning to a more appropriate location. Edit four Access Controls pages for Cloud users Backports #11826 * Edit four Access Controls pages for Cloud users See #10638 Access Controls Getting Started guide - Add a tabbed Prerequisites section for users of different scopes - Use a ScopedBlock to show OIDC and SAML instructions as Tabs for commercial Teleport users and GitHub instructions for OSS Teleport users - Light style/grammar/clarity edits Role Templates - Tabbed Prerequisites section for different scopes - Adjust the visibility of minor details using ScopedBlocks Locking - Add a scoped Tabs component to the Prerequisites section - Add a ScopedBlock to hide CLI- and config file-specific instructions from Cloud users. WebAuthn - Add scoped Tabs to the Prerequisites section - Move Tabs with TabItems for static configurations and dynamic resources into ScopedBlocks. This way, we don't have to show static configuration instructions to Cloud users. - Remove duplicate config field explanations. - Minor style/grammar edits * Respond to PR feedback - Change verbiage re: belonging to a role - Remove U2F migration section
gravitational · Apr 20, 2022 · a133f7f · a133f7f
1 parent 6538551
commit a133f7f
Show file tree

Hide file tree

Showing 16 changed files with 1,050 additions and 632 deletions.
diff --git a/docs/config.json b/docs/config.json
@@ -399,7 +399,8 @@
         "first": "abcd123-insecure-do-not-use-this",
         "second": "efgh456-insecure-do-not-use-this",
         "third": "ijkl789-insecure-do-not-use-this"
-      }
+      },
+      "ca_pin": "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678"
     },
     "fedramp": {
       "control_url": "https://csrc.nist.gov/Projects/risk-management/sp800-53-controls/release-search#!/control?version=5.1&number="

diff --git a/docs/img/github-sso-auth-screen.jpg b/docs/img/github-sso-auth-screen.jpg
diff --git a/docs/img/login-success.jpg b/docs/img/login-success.jpg
diff --git a/docs/pages/access-controls/getting-started.mdx b/docs/pages/access-controls/getting-started.mdx
@@ -3,13 +3,12 @@ title: Getting Started With Access Controls
 description: Get started using Teleport Access Controls.
 ---
 
-# Getting Started
+In Teleport, any local, SSO, or robot user can assigned one or several roles.
+Roles govern access to databases, SSH servers, Kubernetes clusters, Windows
+desktops, 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.
+We will start with local users and preset roles, assign roles to SSO users, and
+wrap up with creating your own role.
 
 ## Prerequisites
 
@@ -21,12 +20,11 @@ with creating your own role.
 
 ## Step 1/3. Add local users with preset roles
 
-Teleport provides [several preset roles](./reference.mdx#preset-roles):
-`editor`, `auditor` and `access`. Members of the `editor` role can modify
-cluster configuration, members of `auditor` role can view audit logs, and
-`access` members can access cluster resources.
+Teleport provides several preset roles: `editor`, `auditor` and `access`. The
+`editor` role authorizes users to modify cluster configuration, the `auditor`
+role to view audit logs, and `access` role to access cluster resources.
 
-Invite a local user Alice as cluster `editor`:
+Invite the local user Alice as cluster `editor`:
 
 ```code
 $ tctl users add alice --roles=editor
@@ -43,27 +41,28 @@ $ tctl users ls
 # alice                editor
 ```
 
-{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */}
-
-You can update user's roles using `tctl users update` command:
+You can update the user's roles using the `tctl users update` command:
 
 ```code
 # 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 roles create a union -
-she will be able to act as a system administrator and auditor at the same time.
+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
 
-We're now going to set up a GitHub connector for Teleport Open Source Edition and Okta for Teleport Enterprise Edition.
+Next, follow the instructions to set up an authentication connector that maps
+users within your SSO solution to Teleport roles.
 
-<Tabs>
-  <TabItem label="Open Source">
-    Save the file below as `github.yaml` and update the fields. You will need to set up
-    [Github OAuth 2.0 Connector](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) app.
-    Any member belonging to the Github organization `octocats` and on team `admin` will be able to assume a built-in role `access`.
+  <ScopedBlock scope={["oss"]}>
+
+    Save the file below as `github.yaml` and update the fields. You will need to
+    set up a
+    [GitHub OAuth 2.0 Connector](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/)
+    app. Any member belonging to the GitHub organization `octocats` and on team
+    `admin` will be able to assume the built-in role `access`.
 
     ```yaml
     kind: github
@@ -72,44 +71,88 @@ We're now going to set up a GitHub connector for Teleport Open Source Edition an
       # connector name that will be used with `tsh --auth=github login`
       name: github
     spec:
-      # client ID of Github OAuth app
+      # client ID of GitHub OAuth app
       client_id: client-id
-      # client secret of Github OAuth app
+      # client secret of GitHub OAuth app
       client_secret: client-secret
       # This name will be shown on UI login screen
-      display: Github
+      display: GitHub
       # Change tele.example.com to your domain name
       redirect_url: https://tele.example.com:443/v1/webapi/github/callback
       # Map github teams to teleport roles
       teams_to_logins:
-        - organization: octocats # Github organization name
-          team: admin            # Github team name within that organization
+        - organization: octocats # GitHub organization name
+          team: admin            # GitHub team name within that organization
           # map github admin team to Teleport's "access" role
           logins: ["access"]
     ```
-  </TabItem>
 
-  <TabItem label="Enterprise" scope={["enterprise"]}>
-    Follow [SAML Okta Guide](../enterprise/sso/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 built-in role `admin`.
+    Create the `github` resource:
 
-    ```yaml
-    kind: saml
-    version: v2
-    metadata:
-      name: okta
-    spec:
-      acs: https://tele.example.com/v1/webapi/saml/acs
-      attributes_to_roles:
-      - {name: "groups", value: "okta-admin", roles: ["access"]}
-      entity_descriptor: |
-        <?xml !!! Make sure to shift all lines in XML descriptor
-        with 4 spaces, otherwise things will not work
+    ```code
+    $ tctl create github.yaml
     ```
+
+  </ScopedBlock>
+
+  <ScopedBlock scope={["enterprise", "cloud"]}>
+
+  Create a SAML or OIDC application that Teleport can integrate with, then
+  create an authentication connector that maps users within your application to
+  Teleport roles.
+
+  <Tabs>
+  <TabItem label="SAML">
+
+  Follow our [SAML Okta Guide](../enterprise/sso/okta.mdx#configure-okta) to
+  create a SAML application.
+
+  Save the file below as `okta.yaml` and update the `acs` field.
+  Any member in Okta group `okta-admin` will assume a built-in role `admin`.
+
+  ```yaml
+  kind: saml
+  version: v2
+  metadata:
+    name: okta
+  spec:
+    acs: https://tele.example.com/v1/webapi/saml/acs
+    attributes_to_roles:
+    - {name: "groups", value: "okta-admin", roles: ["access"]}
+    entity_descriptor: |
+      <?xml !!! Make sure to shift all lines in XML descriptor
+      with 4 spaces, otherwise things will not work
+  ```
+
+  Create the `saml` resource:
+
+  ```code
+  $ tctl create okta.yaml
+  ```
+
   </TabItem>
-</Tabs>
+  <TabItem label="OIDC">
+
+  Follow our [OIDC guides](../enterprise/sso/oidc.mdx#identity-providers) to
+  create an OIDC application.
+
+  Copy the YAML below to a file called `oidc.yaml` and edit the information to
+  include the details of your OIDC application.
+
+  ```yaml
+  (!examples/resources/oidc-connector.yaml!)
+  ```
+
+  Create the `oidc` resource:
+
+  ```code
+  $ tctl create okta.yaml
+  ```
+
+  </TabItem>
+  </Tabs>
+
+  </ScopedBlock>
 
 ## Step 3/3. Create a custom role
 
@@ -128,9 +171,10 @@ spec:
   allow:
     # Logins configures SSH login principals
     logins: ['readonly']
-    # Assigns members of this role to built-in kubernetes group view
+    # Assigns users with this role to the built-in Kubernetes group "view"
     kubernetes_groups: ["view"]
-    # Allow access to SSH nodes, kubernetes clusters, apps or databases labeled with staging or test
+    # Allow access to SSH nodes, Kubernetes clusters, apps or databases 
+    # labeled with "staging" or "test"
     node_labels:
       'env': ['staging', 'test']
     kubernetes_labels:
@@ -139,7 +183,7 @@ spec:
       'type': ['monitoring']
   # The deny rules always override allow rules.
   deny:
-    # deny access to any node, database, app or kubernetes cluster labeled
+    # deny access to any Node, database, app or Kubernetes cluster labeled
     # as prod as any user.
     node_labels:
       'env': 'prod'
@@ -151,7 +195,7 @@ spec:
       'env': 'prod'
 ```
 
-Create a role using `tctl create -f` command:
+Create a role using the `tctl create -f` command:
 
 ```code
 $ tctl create -f /tmp/interns.yaml

diff --git a/docs/pages/access-controls/guides/locking.mdx b/docs/pages/access-controls/guides/locking.mdx
@@ -15,12 +15,12 @@ description: How to lock compromised users or nodes
   deployment.
 </Details>
 
-System administrators can disable a compromised user, node or
-prevent access during cluster maintenance by placing a lock
+System administrators can disable a compromised user or node—or
+prevent access during cluster maintenance—by placing a lock
 on a session, user or host identity.
 
 Teleport will reject new API requests and terminate active
-connections to SSH, database, desktop and Kubernetes sessions
+connections to SSH, database, desktop, and Kubernetes sessions
 matching the lock's target.
 
 A lock can target the following objects or attributes:
@@ -32,7 +32,7 @@ A lock can target the following objects or attributes:
 - a Teleport node by the node's UUID (effectively unregistering it from the
   cluster)
 - a Windows desktop by the desktop's name
-- an [access request](../../enterprise/workflow/index.mdx) by UUID
+- an [Access Request](../../enterprise/workflow/index.mdx) by UUID
 
 ## Prerequisites
 
@@ -42,7 +42,8 @@ A lock can target the following objects or attributes:
 
 ## Step 1/2. Create a lock
 
-To create a new lock, one can run the `tctl lock` command:
+You can create a new lock with the `tctl lock` command. Specify the lock target
+with one of the following options:
 
 <Tabs>
   <TabItem label="Username">
@@ -119,7 +120,9 @@ $ tctl create -f locksmith.yaml
 # role 'locksmith' has been created
 ```
 
-And assign this role to a user. Re-login for this role to take effect.
+And assign this role to a user. The user must log in again for this role to take
+effect.
+
 </Details>
 
 With a lock in force, all established connections involving the lock's target
@@ -140,7 +143,7 @@ $ tctl lock [email protected] --message="Please come back tomorrow." --ttl=
 </Admonition>
 
 <Details title="Under the hood: Lock resource and expiration" opened={false}>
-Note that without specifying `--ttl` or `--expires` the created lock remains in
+Note that without specifying `--ttl` or `--expires`, the created lock remains in
 force until explicitly removed with `tctl rm`.  Refer to `tctl lock --help` for
 the list of all supported parameters.
 
@@ -159,7 +162,7 @@ spec:
 ```
 
 The `kind: lock` resources can also be created and updated using `tctl create`
-as per usual, see the [Admin Guide](../../setup/reference/resources.mdx) for more
+as per usual. See the [Admin Guide](../../setup/reference/resources.mdx) for more
 details.
 </Details>
 
@@ -182,20 +185,24 @@ Deleting a lock will allow new sessions or host connections.
 
 ## Next steps: Locking modes
 
-If a Teleport node or proxy cannot properly synchronize its local lock view
-with the backend, there is a decision to be made about whether to rely on the
-last known locks. This decision strategy is encoded as one of the two modes:
+If a Teleport node or Proxy Service cannot properly synchronize its local lock
+view with the backend, there is a decision to be made about whether to rely on
+the last known locks. This decision strategy is encoded as one of the two modes:
 - `strict` mode causes all interactions to be terminated when the locks are not
   guaranteed to be up to date
 - `best_effort` mode keeps relying on the most recent locks
 
-The cluster-wide mode defaults to `best_effort`.
-You can set up default locking mode via API or CLI using resource `cluster_auth_preference`
-or static configuration file:
+<ScopedBlock scope={["oss", "enterprise"]}>
+
+The cluster-wide mode defaults to `best_effort`. You can set up the default
+locking mode via API or CLI using a `cluster_auth_preference` resource or static
+configuration file:
 
 <Tabs>
   <TabItem label="API or CLI">
-    Create a YAML file `cap.yaml` or get the existing file using `tctl get cap`
+
+    Create a YAML file called `cap.yaml` or get the existing file using
+    `tctl get cap`.
 
     ```yaml
     kind: cluster_auth_preference
@@ -214,18 +221,45 @@ or static configuration file:
     ```
   </TabItem>
   <TabItem label="Static Config">
-    Edit the `teleport.yaml` of the Auth server:
+    Edit `/etc/teleport.yaml` on the Auth Server:
 
     ```yaml
     auth_service:
         authentication:
             locking_mode: best_effort
     ```
 
-    Restart the auth server for the change to take effect.
+    Restart the Auth Server for the change to take effect.
   </TabItem>
 </Tabs>
 
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+The cluster-wide mode defaults to `best_effort`. You can set up the default
+locking mode via API or CLI using a `cluster_auth_preference` resource:
+
+Create a YAML file called `cap.yaml` or get the existing file using
+`tctl get cap`.
+
+```yaml
+kind: cluster_auth_preference
+metadata:
+  name: cluster-auth-preference
+spec:
+  locking_mode: best_effort
+version: v2
+```
+
+Create a resource:
+
+```code
+$ tctl create -f cap.yaml
+# cluster auth preference has been updated
+```
+
+</ScopedBlock>
+
 It is also possible to configure the locking mode for a particular role:
 
 ```yaml