diff --git a/docs/pages/setup/admin/users.mdx b/docs/pages/setup/admin/users.mdx
index fd232180f41a9..29fb57d944337 100644
--- a/docs/pages/setup/admin/users.mdx
+++ b/docs/pages/setup/admin/users.mdx
@@ -3,7 +3,18 @@ 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 as well as OIDC and SAML
+2.0.
+
+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
@@ -11,9 +22,7 @@ This guide explains how to invite users and manage local user accounts.
(!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,9 +31,9 @@ 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:
@@ -32,14 +41,14 @@ Let's add a new user to Teleport using the `tctl` tool:
$ 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://: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://:443/web/invite/
-# NOTE: make sure the host is accessible.
+NOTE: Make sure :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
```
-
-
-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
-```
-
-
-
-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
-```
-
-
-
-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
-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)
+
-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).