Improve the usability of the Local Users guide (#12001)

* Improve the usability of the Local Users guide See #11841 - Define "local users" at the beginning of the guide - Split the "Adding and deleting users" section and move the "Deleting users" section after the "Editing users" section. This way, readers can follow all commands in the guide. Otherwise, the new user is deleted before being edited. - Hide scope-irrelevant details - Remove a "tsh ssh" command that a reader may not necessarily have set up Teleport to run properly. * Respond to PR feedback
gravitational · Apr 18, 2022 · d9a0584 · d9a0584
1 parent 334483b
commit d9a0584
Showing 1 changed file with 47 additions and 43 deletions.
diff --git a/docs/pages/setup/admin/users.mdx b/docs/pages/setup/admin/users.mdx
@@ -3,17 +3,26 @@ title: Local Users
 description: Adding and deleting local users
 ---
 
-This guide explains how to invite users and manage local user accounts.
+In Teleport, **local users** are users managed directly via Teleport, rather
+than a third-party identity provider.
+
+Local user accounts can be used alongside external user accounts managed via
+GitHub<ScopedBlock scope={["enterprise", "cloud"]}> as well as OIDC and SAML
+2.0</ScopedBlock>.
+
+This guide shows you how to:
+
+- [Add local users](./users.mdx#adding-local-users)
+- [Edit existing users](./users.mdx#editing-users)
+- [Delete users](./users.mdx#deleting-users)
 
 ## Prerequisites
 
 (!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
 (!docs/pages/includes/tctl.mdx!)
 
-## Adding and deleting users
-
-Teleport's local user accounts are created and stored in Teleport's internal storage.
+## Adding local users
 
 A user identity in Teleport exists in the scope of a cluster.
 A Teleport administrator creates Teleport user accounts and maps them to the roles they can use.
@@ -22,24 +31,24 @@ Let's look at this table:
 
 | Teleport User | Allowed OS Logins | Description |
 | - | - | - |
-| `joe` | `joe`, `root` | Teleport user `joe` can log in into member Nodes as OS user `joe` or `root` |
-| `bob` | `bob` | Teleport user `bob` can log in into member Nodes only as OS user `bob` |
-| `ross` | | If no OS login is specified, it defaults to the same name as the Teleport user `ross`. |
+| `joe` | `joe`, `root` | Teleport user `joe` can log in to member Nodes as user `joe` or `root` on the OS. |
+| `bob` | `bob` | Teleport user `bob` can log in to member Nodes only as OS user `bob`. |
+| `kim` | | If no OS login is specified, it defaults to the same name as the Teleport user, `kim`. |
 
 Let's add a new user to Teleport using the `tctl` tool:
 
 ```code
 $ tctl users add joe --logins=joe,root --roles=access,editor
 ```
 
-Teleport generates an auto-expiring token (with a TTL of 1 hour) and prints the
-token URL, which must be used before the TTL expires.
+Teleport generates an auto-expiring token (with a TTL of one hour) and prints
+the token URL, which must be used before the TTL expires.
 
 ```code
-# Signup token has been created. Share this URL with the user:
-# https://<proxy>:3080/web/newuser/xxxxxxxxxxxx
+User "joe" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:
+https://<proxy_host>:443/web/invite/<token>
 
-# NOTE: make sure the <proxy> host is accessible.
+NOTE: Make sure <proxy_host>:443 points at a Teleport proxy which users can access.
 ```
 
 The user completes registration by visiting this URL in their web browser,
@@ -60,39 +69,13 @@ $ tctl users ls
 # User           Allowed Logins
 # ----           --------------
 # admin          admin,root
-# ross           ross
+# kim            kim
 # joe            joe,root
 ```
 
-<Tabs>
-<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
-Joe can then use the `tsh` client tool to log in to the Teleport Node "luna" via
-bastion "work" as `root`:
-
-```code
-$ tsh --proxy=work --user=joe root@luna
-```
-</TabItem>
-<TabItem scope={["cloud"]} label="Teleport Cloud">
-
-Joe can then use the `tsh` client tool to log in to the Teleport Node "luna" via
-Teleport Cloud as `root`. Joe's Teleport Cloud tenant URL is `mytenant.teleport.sh`.
-
-```code
-$ tsh --proxy=mytenant.teleport.sh --user=joe root@luna
-```
-</TabItem>
-</Tabs>
-
-To delete this user:
-
-```code
-$ tctl users rm joe
-```
-
 ## Editing users
 
-Admins can edit user entries with the [resource commands](../reference/resources.mdx) via [`tctl`](../reference/cli.mdx#tctl).
+Admins can edit user entries via `tctl`.
 
 For example, to see the full list of user records, an administrator can execute:
 
@@ -111,19 +94,40 @@ $ tctl get user/joe > joe.yaml
 $ tctl create -f joe.yaml
 ```
 
-## Further reading
+## Deleting users
+
+Admins can delete a local user via `tctl`:
+
+```code
+$ tctl users rm joe
+```
+
+## Next steps
 
 <Tabs>
 <TabItem scope={["enterprise", "cloud"]} label="Commercial">
-You can configure Teleport so that users can log in using an SSO provider.
+
+In addition to users, you can use `tctl` to manage roles and other dynamic
+resources. See our [Teleport Resources Reference](../reference/resources.mdx).
+
+For all available `tctl` commands and flags, see our [CLI Reference](../reference/cli.mdx#tctl).
+
+You can also configure Teleport so that users can log in using an SSO provider.
 For more information, see:
 
 - [Single Sign-On](../../enterprise/sso.mdx)
 - [GitHub SSO](./github-sso.mdx)
+
 </TabItem>
 <TabItem scope={["oss"]} label="Open Source">
 
-You can configure Teleport so that users can log in using GitHub. For more
+In addition to users, you can use `tctl` to manage roles and other dynamic
+resources. See our [Teleport Resources Reference](../reference/resources.mdx).
+
+For all available `tctl` commands and flags, see our
+[CLI Reference](../reference/cli.mdx#tctl).
+
+You can also configure Teleport so that users can log in using GitHub. For more
 information, see [GitHub SSO](./github-sso.mdx).
 
 </TabItem>